feat(gui): Wallet (watch-only) — descriptors + derived addresses + manage sources

[Noyi-24-7]

Summary

Watch-only Wallet screen for Floresta GUI (v0), using a descriptor-first model.

Goal: allow users to import one or more wallet descriptors (“tracking sources”), derive addresses, scan for balances/txs, and review results in a simple friendly UI (no spending, no private keys).

Parent index: #1

---

What’s designed (current)

• Wallet EMPTY screen (no descriptors yet)
• Add Descriptor modal
• Wallet with descriptors added — Derived Addresses (List view)
• Wallet with descriptors added — Derived Addresses (Table view)
• Manage Sources (right sidebar modal/drawer)

---

Frame(s)

• Wallet — EMPTY: FIGMA_LINK_FRAME_11
• Wallet — Add Descriptor modal: FIGMA_LINK_FRAME_12
• Wallet — Descriptors Added (Derived Addresses: List): FIGMA_LINK_FRAME_13
• Wallet — Descriptors Added (Derived Addresses: Table): FIGMA_LINK_FRAME_14
• Wallet — Manage Sources (Right Sidebar): FIGMA_LINK_FRAME_15

(Links tracked in design/figma-links.md.)

---

Model (v0 / Option B)

• Tracking Sources = Descriptors
  • Users add one or more descriptors (watch-only).
• Derived Addresses = addresses derived from descriptors
  • UI shows derived addresses grouped/filtered by descriptor source.
• No private keys, no sending/spending.

---

Layout / Sections (Wallet main screen)

A) Watch-only banner

• Clear “watch-only” explanation (can see, cannot spend)
• Primary CTA: Add descriptor
• Secondary actions (optional): Rescan

B) Balances

• Confirmed balance
• Unconfirmed balance
  Notes:
• Global totals reflect the selected filter scope (e.g., All descriptors vs single descriptor).

C) Tracking Sources summary

• “X descriptors • Y derived addresses • Last scan …”
• CTA: Manage sources (opens right sidebar)

D) Derived Addresses

• Default view: List view (friendly)
• Optional toggle: List ↔ Table
• Filter: Source = All descriptors / specific descriptor
• Each row shows:
  • Label (if any)
  • Address snippet + Copy
  • Source (descriptor name)
  • Amount (BTC)
  • Last active

E) Recent Activity (if present in your design)

• Tx rows: amount, date, status chip (Confirmed/Unconfirmed), txid snippet + Copy

---

Add Descriptor modal

Inputs

• Descriptor name/label (optional but helpful)
• Descriptor textarea input
• Helper copy explaining descriptors in simple terms

Actions

• Cancel
• Add / Save
• On success: descriptor appears in sources; scanning begins (or queued)

Validation (v0-friendly)

• Empty input
• Invalid descriptor format (show gentle error + link to help/docs if available)
• Duplicate descriptor (warn)

---

Manage Sources right sidebar modal/drawer

Shows descriptor list with:

• Name/label
• Derived address count (e.g., 120)
• Scan status (Ready / Scanning / Error)
• (Optional but useful) per-descriptor confirmed/unconfirmed totals
  Actions per source:
• Copy descriptor
• Rescan
• Remove (with confirm)

Also includes CTA:

• “+ Add another descriptor” (opens Add Descriptor modal)

---

States covered (in current design)

• EMPTY ✅
• READY ✅ (descriptors added)
• LOADING: UNKNOWN (scan in progress) (Coming Soon!)
• ERROR: UNKNOWN (descriptor invalid / scan failure / index unavailable) (Coming Soon!)
• LOCKED: UNKNOWN (wallet index off) (Coming Soon!)

---

Questions for maintainers

1. Confirm v0 model: descriptor-only import (no standalone address import), correct?
2. Any preferred naming for descriptor actions: “Import descriptor” vs “Add descriptor”? Is the naming convention alright for everything?
3. Should per-descriptor balances be shown in Manage Sources (drawer), or keep it minimal for v0?
4. Should “Unconfirmed” be shown always, or only when mempool data is available?
5. Is it fine to have both the list and table view or is one prefered to the other?

---

Acceptance notes (implementation later)

• Desktop-first
• Descriptor-first flow is obvious (sources → derived addresses)
• Manage Sources interaction works (click opens drawer/screen)
• Clear watch-only messaging (no keys, no spending)
• Copy buttons for address/descriptor/txid are present + toasts