Dust Attack - identification and resolution.

[antuz123]

Feature Description

Add basic dust attack protection to Keeper.

A dust attack happens when someone sends a very small bitcoin amount to a wallet address, usually an old, reused, or unusual address. If the wallet later spends that small UTXO together with other coins, it may reduce the user’s privacy by linking those coins together.

Keeper should detect these suspicious small UTXOs and mark them as Do Not Spend, so they are not used automatically during normal sends.

Problem

Keeper currently allows all UTXOs to be treated as spendable unless the user manually manages them.

This means a small suspicious UTXO may get selected automatically during a send transaction. If that happens, the dust UTXO can get combined with normal wallet funds and may reveal links between wallet addresses or UTXOs.

This is a privacy issue, not a fund-loss issue.

Why This Matters

Users may not notice tiny incoming transactions.

If they later spend normally, Keeper may unknowingly include that dust UTXO in coin selection. This can weaken wallet privacy.

Keeper already has UTXO management, so this should be handled inside the existing coin control flow instead of creating a new dust-specific screen.

How Keeper Identifies It

Keeper should treat a UTXO as potential dust if:

• the UTXO amount is below 5,000 sats
• and it was received on a reused or out-of-order / unusual wallet address

If both conditions are true, Keeper marks the UTXO as:

Do Not Spend

Keeper should ignore mass-dusting transaction-pattern detection for this version.

Where This Applies

This should apply whenever Keeper scans or refreshes wallet UTXOs:

• wallet creation
• wallet import / restore
• wallet opened after app upgrade
• normal wallet refresh
• new incoming transaction scan

Every wallet-owned UTXO should have one spendability state:

• Spendable
• Do Not Spend

If a UTXO does not yet have a state, Keeper should classify it during the scan.

Already Spent Dust

If Keeper identifies that a potential dust UTXO was already spent, it should:

• mark the related transaction as a potential dust spend
• identify any current wallet-owned descendant UTXOs affected by that spend
• mark those affected current UTXOs as Do Not Spend

User Visibility

Keeper should show this in existing wallet and UTXO areas.

Home wallet list

• Show the customary red dot on a wallet card/item if that wallet contains any Do Not Spend UTXO.

Wallet details

• Show a small non-tappable line below the wallet name/subtitle:
  Includes Do Not Spend coins

More Options

• Show the customary red dot on View All Coins if the wallet has Do Not Spend coins.

Manage Coins

• Show the Do Not Spend label clearly on affected UTXOs.

UTXO Details

• Show why the coin is marked Do Not Spend.
• Allow user to explicitly mark it spendable.

Send Behaviour

Normal send coin selection should exclude Do Not Spend UTXOs.

If the user’s total wallet balance is higher than the amount available to spend because some coins are marked Do Not Spend, Keeper should explain this in the send flow.

Manual Control

Users should also be able to manually mark any UTXO as Do Not Spend, even if Keeper did not detect it as potential dust.

Users should also be able to explicitly mark a Do Not Spend UTXO as spendable from UTXO details.

Design

Use existing Keeper screens and patterns:

• Wallet home list
• Wallet details
• More Options
• View All Coins
• Manage Coins
• UTXO Details
• Send flow

Do not create a new standalone dust screen.

[antuz123]

Feature Title

Dust Attack Protection and Donate Dust

Context

Bitcoin Keeper already has UTXO management through:

Wallet → More Options → View All Coins → Manage Coins

Dust attacks are privacy attacks. They happen when a very small bitcoin amount is sent to a wallet address and later gets spent with other wallet coins. This can link wallet UTXOs together and reduce privacy.

Keeper should identify potential attack dust, mark affected coins as Do Not Spend, exclude them from normal sends, and give users an optional way to donate dust using only those Do Not Spend coins.

Goal

Add a simple spendability model for wallet-owned UTXOs:

• Spendable
• Do Not Spend

Keeper should automatically mark likely dust attack UTXOs and affected descendant UTXOs as Do Not Spend.

Users should also be able to manually mark any UTXO as Do Not Spend and later mark it spendable again.

Non-Goals

• Do not create multiple dust risk levels.
• Do not create a standalone dust screen.
• Do not detect mass-dusting transaction patterns in this version.
• Do not treat all low-value UTXOs as dust.
• Do not include general economic dust cleanup.
• Do not use normal spendable UTXOs to pay fees for dust donation.
• Do not apply out-of-order address detection to change addresses.
• Do not use the word “Vault” in user-facing copy.

User Flow

Wallet creation / import / restore

1. User creates, imports, or restores a wallet.
2. Keeper scans wallet transactions and builds the UTXO list.
3. Keeper classifies any UTXO without spendability state.
4. Potential attack-dust UTXOs are marked Do Not Spend.
5. Normal UTXOs are marked Spendable.
6. If historical dust was already spent, Keeper marks traceable current wallet-owned descendant UTXOs as Do Not Spend.
7. If the wallet has current Do Not Spend coins, UI indicators appear.

Existing wallet after app update

1. User opens an existing wallet after updating Keeper.
2. Normal wallet scan runs.
3. UTXOs without spendability state are classified.
4. No global upgrade script is required.
5. Wallet indicators appear if current Do Not Spend coins exist.

New incoming transaction

1. Wallet refresh detects a new UTXO.
2. Keeper checks the dust rules.
3. If the UTXO is potential attack dust, it is marked Do Not Spend.
4. Show one-time toast:
   Potential dust payment found

Normal send

1. User starts a normal send.
2. Automatic coin selection excludes Do Not Spend coins.
3. Available balance excludes Do Not Spend coins.
4. If total wallet balance is enough but spendable balance is not enough, Keeper explains this in the send flow.

Manual coin control

1. User opens View All Coins.
2. User opens UTXO Details.
3. User can mark a spendable coin as Do Not Spend.
4. User can mark a Do Not Spend coin as spendable.

Donate Dust

1. User opens Manage Coins.
2. If eligible Do Not Spend coins exist, Keeper shows CTA:
   Donate Dust
3. Keeper prepares donation using all eligible Do Not Spend coins.
4. User reviews and confirms.
5. Fees are paid only from those selected Do Not Spend UTXOs.
6. Keeper must never add normal spendable UTXOs.
7. Any remaining amount after fees is sent to:

bc1qyqequr0824nwf7snzvq5gqsr6xscn62e3ttm06

8. If the selected coins cannot create a valid transaction by themselves, Keeper keeps them marked Do Not Spend and shows an error.

Screens / States

Wallet Home List

Screen type: Wallet list / wallet cards

Title: Existing screen title unchanged

Body copy: None

Button labels: Existing buttons unchanged

Warnings / info text: None

Error text: None

Success text: None

Behaviours:

• If a wallet has any current Do Not Spend UTXO, show the customary red dot on that wallet item/card.
• This applies for current Do Not Spend coins from new dust, historical dust, linked descendants, or user-marked Do Not Spend coins.
• Do not show warning text on the home wallet list.
• Do not change wallet balance display on the home wallet list.

Navigation transitions:

• Tapping wallet opens Wallet Details as currently implemented.

---

Wallet Details

Screen type: Wallet detail screen

Title: Existing wallet name

Body copy: Existing wallet subtitle unchanged

Button labels: Existing wallet actions unchanged

Warnings / info text:

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

Includes Do Not Spend coins

Error text: None

Success text: None

Behaviours:

• Text is informational only.
• Text is not tappable.
• Do not show a warning card here.
• Do not show a modal from this line.

Navigation transitions:

• User can open More Options → View All Coins to inspect coins.

---

More Options Bottom Sheet

Screen type: Bottom sheet

Title: Existing title unchanged

Body copy: None

Button labels:

• View All Coins
• Manage Keys

Warnings / info text: None

Error text: None

Success text: None

Behaviours:

• If wallet has any current Do Not Spend UTXO, show the customary red dot on View All Coins.
• Do not add explanatory text inside this bottom sheet.

Navigation transitions:

• View All Coins opens Manage Coins.
• Manage Keys unchanged.

---

Manage Coins

Screen type: UTXO list / coin management screen

Title: Manage Coins

Body copy: Existing screen content unchanged

Button labels:

• Existing Select to Send
• New CTA when eligible Do Not Spend coins exist:
  Donate Dust

Warnings / info text: None at top level unless existing component pattern requires it

Error text:

If Donate Dust cannot build a valid transaction using only eligible Do Not Spend coins:

These coins are too small to donate on their own. Keeper will keep them marked Do Not Spend.

Success text:

Dust donated

Behaviours:

• Show all wallet-owned UTXOs.
• Show existing labels like Change and Self.
• Show Do Not Spend label clearly on affected coins.
• Use warning-style label treatment for Do Not Spend.
• Do Not Spend coins remain visible.
• Do Not Spend coins are excluded from normal sends.
• User can open UTXO Details for reason and actions.
• Show Donate Dust only when there are eligible Do Not Spend coins.
• Donate Dust uses all eligible Do Not Spend coins by default.
• User can decide not to continue on confirmation.

Navigation transitions:

• Tapping a coin opens UTXO Details.
• Select to Send follows existing manual UTXO send flow.
• Donate Dust opens Donate Dust confirmation.

---

UTXO Details: Spendable Coin

Screen type: Coin detail screen

Title: Existing UTXO detail title

Body copy: Existing coin details unchanged

Button labels:

Mark Do Not Spend

Warnings / info text: None

Error text: None

Success text:

Coin marked Do Not Spend

Behaviours:

• User can manually mark any spendable UTXO as Do Not Spend.
• Manual Do Not Spend state persists across refreshes.
• Manual state is not removed by automatic classification.

Navigation transitions:

• After action, remain on UTXO Details and update state.
• Back returns to Manage Coins.

---

UTXO Details: Do Not Spend Coin

Screen type: Coin detail screen

Title: Existing UTXO detail title

Body copy: Existing coin details unchanged

Button labels:

Mark Spendable

Warnings / info text:

Show one reason:

Potential dust payment

or

Linked to potential dust spend

or

Marked manually

For system-marked coins, show:

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

Error text: None

Success text:

Coin marked spendable

Behaviours:

• System-marked Do Not Spend must not be removable like a normal label/tag.
• User must use explicit CTA Mark Spendable.
• Once user marks it spendable, persist the override.
• Do not automatically re-mark the same UTXO as Do Not Spend on the next scan unless future rules explicitly require it.

Navigation transitions:

• After action, remain on UTXO Details and update state.
• Back returns to Manage Coins.

---

New Dust Detection Toast

Screen type: Toast

Title: None

Body copy:

Potential dust payment found

Button labels: None

Warnings / info text: None

Error text: None

Success text: None

Behaviours:

• Show once when a new potential dust payment is detected during wallet refresh.
• Do not show repeatedly for already-known Do Not Spend coins.
• Do not show for historical scan if it would create too much noise during import/restore.

Navigation transitions: None

---

Send Flow

Screen type: Existing Send Bitcoin flow

Title: Existing send titles unchanged

Body copy: Existing send copy unchanged

Button labels:

Existing send CTAs unchanged.

When balance issue is caused by Do Not Spend coins:

View Coins

Warnings / info text:

If total balance is enough but spendable balance is not enough:

Some coins are marked Do Not Spend and are not available for this payment.

Error text:

Use existing insufficient balance error, with the helper copy above when relevant.

Success text: Existing send success unchanged

Behaviours:

• Normal coin selection excludes Do Not Spend coins.
• Available balance excludes Do Not Spend coins.
• Do Not Spend coins are never selected automatically.
• If user enters amount greater than spendable balance but less than or equal to total balance, show helper copy.
• Manual UTXO selection can show Do Not Spend coins, but selecting them requires explicit warning.

Navigation transitions:

• View Coins opens Manage Coins.
• Send confirmation remains unchanged except selected inputs exclude Do Not Spend coins by default.

---

Manual UTXO Selection Warning

Screen type: Warning modal / bottom sheet

Title:

Use Do Not Spend Coin?

Body copy:

This coin was marked Do Not Spend to help protect wallet privacy. Spending it with other coins may reduce privacy.

Button labels:

• Use Coin
• Cancel

Warnings / info text: Body copy above

Error text: None

Success text: None

Behaviours:

• Show only when user manually selects a Do Not Spend coin for spending.
• Do not show during normal automatic coin selection because Do Not Spend coins are excluded.

Navigation transitions:

• Use Coin includes the selected coin in manual selection.
• Cancel returns to manual coin selection.

---

Donate Dust Confirmation

Screen type: Confirmation modal / bottom sheet

Title:

Donate Dust?

Body copy:

This helps clear dust / Do Not Spend coins for better privacy. Keeper will use only Do Not Spend coins for this transaction. Fees will be paid from those coins only.

Button labels:

• Donate Dust
• Cancel

Warnings / info text:

No spendable coins will be used.

If useful in review details:

Any amount left after fees will be donated to support Keeper.

Error text:

If transaction cannot be built using only eligible Do Not Spend coins:

These coins are too small to donate on their own. Keeper will keep them marked Do Not Spend.

Success text:

Dust donated

Behaviours:

• Donate Dust uses all eligible Do Not Spend coins.
• User can cancel.
• Fees must come only from those Do Not Spend UTXOs.
• Never add normal spendable UTXOs.
• Use minimum fee rate.
• Remaining amount after fees goes to Keeper donation address:
  bc1qyqequr0824nwf7snzvq5gqsr6xscn62e3ttm06
• If a valid donation output cannot be created, selected value may not be sent unless a valid fee-only transaction can be safely built by existing transaction rules.
• If no valid transaction can be built, keep coins marked Do Not Spend.

Navigation transitions:

• Donate Dust proceeds to existing transaction review/signing flow.
• Cancel returns to Manage Coins.

---

Transaction History / Transaction Detail

Screen type: Transaction list and transaction detail

Title: Existing transaction titles unchanged

Body copy: Existing transaction copy unchanged

Button labels: Existing buttons unchanged

Warnings / info text:

For a transaction that spent potential dust:

Potential dust spend

Transaction detail explanation:

This transaction may have spent a suspicious small amount together with other wallet funds. This may have reduced wallet privacy.

Error text: None

Success text: None

Behaviours:

• If a historical potential dust UTXO was already spent, mark the spending transaction.
• This is informational only.
• No action is shown for the already-spent dust.
• Current traceable affected descendant UTXOs are marked Do Not Spend where applicable.
• A historical Potential dust spend alone does not show red dot unless there are current Do Not Spend coins.

Navigation transitions:

• Existing transaction detail navigation unchanged.

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
• Potential dust payment
• Linked to potential dust spend
• Marked manually
• Potential dust spend
• Donate Dust
• Dust donated

Use these exact explanation lines:

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

Some coins are marked Do Not Spend and are not available for this payment.

This helps clear dust / Do Not Spend coins for better privacy. Keeper will use only Do Not Spend coins for this transaction. Fees will be paid from those coins only.

No spendable coins will be used.

These coins are too small to donate on their own. Keeper will keep them marked Do Not Spend.

Do not use:

• crypto
• cryptocurrency
• vault
• infected
• quarantine
• low risk / medium risk / 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.
• Do not add heavy warnings to wallet home.
• Do not make Includes Do Not Spend coins tappable.
• Keep copy short and mobile-safe.
• Do not truncate security-relevant copy.
• Use stacked buttons if horizontal buttons do not fit small screens.
• Keep Donate Dust contextual inside Manage Coins only.

Existing Components

Reuse:

• Wallet card/list item
• Wallet Details header
• More Options bottom sheet
• Manage Coins list
• UTXO label/chip component
• UTXO Details screen
• Send Bitcoin flow
• Manual coin selection flow
• Confirmation modal / bottom sheet
• Toast component
• Transaction list item
• Transaction detail warning/info pattern
• Existing red dot alert indicator
• Existing transaction review/signing flow

Existing Assets

No new assets required.

Use existing:

• red dot indicator
• warning label style
• coin row styles
• confirmation modal / bottom sheet components
• toast component

Assets & References

Donation address for Donate Dust:

bc1qyqequr0824nwf7snzvq5gqsr6xscn62e3ttm06

SVG Requirements

None.

Implementation Notes

UTXO spendability state

Every wallet-owned UTXO should have persisted spendability state:

• Spendable
• Do Not Spend

If a current wallet-owned UTXO does not have a state, classify it during the next wallet scan.

Normal UI should not show a Spendable label on every coin unless existing design needs it. Only Do Not Spend needs visible label treatment.

Efficient address metadata

Keeper should make detection efficient by storing lightweight address metadata per wallet:

• address

• addressIndex

• addressType:

  • receive
  • change

• hasReceivedBefore

• highestReceivedReceiveAddressIndex

• previousReceiveCount

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

Detection rule

Mark a UTXO Do Not Spend when:

Amount is under 5,000 sats, and either:

Receive address rule

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

Change address rule

• 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.

Scan points

Run classification during:

• wallet creation
• wallet import / restore
• wallet opened after app update
• normal wallet refresh
• pull-to-refresh
• new incoming transaction scan

No separate global upgrade script is required.

Classification rule

When wallet scan runs:

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

Already-spent potential dust

If a historical UTXO would have met potential dust rules but has already been spent:

• mark the spending transaction as Potential dust spend
• trace current wallet-owned descendant UTXOs where possible
• mark all traceable current affected descendant UTXOs as Do Not Spend
• reason:
  Linked to potential dust spend

This should apply across descendant layers where traceable, not only one layer.

Red dot state

Show red dot when wallet has any current Do Not Spend UTXO.

This includes:

• potential dust payment
• linked to potential dust spend
• manually marked Do Not Spend

Do not show red dot for historical Potential dust spend alone if there are no current Do Not Spend coins.

Donate Dust eligibility

Donate Dust should include all current Do Not Spend coins.

This includes:

• potential dust payment
• linked to potential dust spend
• manually marked Do Not Spend

User can cancel on confirmation.

Donate Dust must never include normal Spendable coins.

Donate Dust transaction rule

Donate Dust must:

• use only Do Not Spend UTXOs
• pay fees only from those UTXOs
• never add normal spendable UTXOs
• use minimum fee rate
• send leftover donation amount to:
  bc1qyqequr0824nwf7snzvq5gqsr6xscn62e3ttm06
• fail gracefully if no valid transaction can be built

Balance handling

• Total wallet balance can include all wallet-owned UTXOs.
• Available / spendable balance excludes Do Not Spend UTXOs.
• Explain the difference only when relevant in Send flow.

Acceptance Criteria

UTXO classification

• 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.
• User override persists after refresh.

Wallet creation / import / restore

• Dust classification runs after wallet creation scan.
• Dust classification runs after wallet import / restore scan.
• Suspicious unspent dust is marked Do Not Spend.
• Already-spent potential dust marks traceable current descendant UTXOs as Do Not Spend.

Existing users after update

• Existing wallet opened after app update classifies UTXOs without spendability state.
• No global upgrade script is required.
• Affected wallet shows red dot on home wallet item/card.
• Affected wallet shows Includes Do Not Spend coins in Wallet Details.
• View All Coins shows red dot in More Options.

New incoming dust

• New potential dust detected during wallet refresh is marked Do Not Spend.
• Toast appears once:
  Potential dust payment found
• Toast does not repeat for the same already-known UTXO.

Manage Coins

• Do Not Spend coins remain visible.
• Do Not Spend label appears clearly.
• Existing labels like Change and Self continue to work.
• User can open details for Do Not Spend coins.
• User can manually mark a normal coin as Do Not Spend.
• Donate Dust appears when current Do Not Spend coins exist.

UTXO Details

• Spendable coin shows Mark Do Not Spend.
• Do Not Spend coin shows Mark Spendable.
• System-marked coin shows correct reason.
• Manual coin shows Marked manually.
• Mark Spendable persists after refresh.
• System-marked Do Not Spend cannot be removed like a normal label.

Send flow

• Normal send excludes Do Not Spend coins.
• Available balance excludes Do Not Spend coins.
• If total balance is enough but spendable balance is not enough, helper copy is shown.
• Manual selection of Do Not Spend coin requires warning confirmation.

Transaction history

• Transaction that spent potential dust is labelled Potential dust spend.
• Transaction detail explains possible privacy impact.
• No action is shown for already-spent dust itself.
• Current traceable affected descendant UTXOs are marked Do Not Spend.

Donate Dust

• Donate Dust uses all current Do Not Spend coins.
• Donate Dust never adds Spendable coins.
• Fees are paid only from Do Not Spend coins.
• Remaining amount after fees goes to:
  bc1qyqequr0824nwf7snzvq5gqsr6xscn62e3ttm06
• User must confirm before donation transaction proceeds.
• User can cancel.
• If transaction cannot be built using only Do Not Spend coins, show:
  These coins are too small to donate on their own. Keeper will keep them marked Do Not Spend.
• Successful donation shows:
  Dust donated