Six panes, vault, passkeys, holds, agents — one app for money+chat+compute · content/guides/using-the-wallet.md
Using the Wallet — one app for money, chat and compute
Qal Wallet, the desktop app: what each part does, what to press, what success looks like.
✓ verified against wallet-app v7 (2026-09-11) + the live command surface, 2026-09-12 — onboarding, vault, tabs and the command layer (loopd :8823 · relay :8830 · qmarket :8824, all green) walked from the v7 README and exercised via the same commands the app drives (qalchat.py, seedkit/derive.py, vault.py). Full GUI click-through on Windows/macOS pending — flagged where that matters.
What you need
- Windows, macOS or Linux desktop (1280×800 minimum). No npm, no build step — vanilla UI over a thin Rust command layer.
- The local services up:
bash scripts/status.sh(chain, loopd, relay are the ones the wallet talks to). - Run it:
cargo tauri devinwallet-app/(dev), or the production build (see wallet-app/README §Run).
First run — onboarding
| Path | What happens |
|---|---|
| Create account | Pick a handle → 12 words shown once (grid + copy + "I wrote it down" checkbox) → keys derived → set app password → success screen: your qoll code. The words are discarded from memory on the very next step; the wallet never writes a seed stub. |
| Restore from seed | Type 12/24 words → identical keys re-grow (byte-for-byte). See login-and-accounts for the walkthrough. |
| Import identity file | Paste identity JSON (public-only files refused) or unwrap an encrypted export container (Settings ▸ Export — an AES container in ~/Downloads with its own password). |
Existing CLI users get a one-click "Set an app password" — the vault then encrypts every identity's secret fields on disk.
The six panes
Ctrl/Cmd 1–6 switches · Ctrl/Cmd L locks · Esc dismisses.
| Pane | What it does | Success looks like |
|---|---|---|
| Wallet | Balance + reserve-backed ✓ badge, holds (115% pre-auths), Send (HMAC-signed), Topup (transfer from the issuer wallet; paper-mode test cents in phase 0), activity feed |
5.00 B-QALS, feed shows the transfer with its receipt id |
| Chat | Full messenger: rail, threads, bubbles, ticks, day separators, 📎 attach menu (📷 / 📄 / ⚡ / 🔒), find, mute, unread badges, Channels | Gold ⚡ badge with settle id; ✓ → ⚓ after anchoring |
| Compute | Live price board, converter, Buy (hold → execute → settle → anchor), job history | Job card with receipt + anchor tx/sha256 in the context pane |
| Contacts | qoll codes, full fingerprints, pin source (invite/code/tofu), My invite QR, add-person (TOFU-warned) |
Red banner = key substitution blocked — never ignore it |
| Files | Send to pinned contacts; received list; every file auto-anchored on receive | Per-file ⚓ tx inline |
| Agents | loopd agents, their daily caps, revoke/restore | A capped, revocable key per bot — the "what may this bot do today" layer |
The right-hand context pane always shows the selected thing's verification state: peer pin status, job receipt, file sha256 + anchor, or your own qoll code (click to copy).
Money moves in the wallet
- Send: Wallet ▸ Send ▸ handle ▸ cents ▸ confirm. The transfer is HMAC-signed with your device-held secret and settles atomically; the receipt id appears in the activity feed.
- Top up: card payment via the payments bridge when sales open; today,
topupissues paper-mode test cents (honest phase: no real dollars move — ground truth F21). - Units: the app shows Qals with decimals (
0.25 B-QALS); hover an amount to see doofs (1 Qal = 1,000,000 doofs). - Holds: anything job-shaped places a 115% pre-authorisation first, then settles the exact amount and releases the rest — petrol-station pre-auth, in app form.
Locking, passkeys, and what the password protects
- The app password encrypts the vault (all identities' secrets, AES-256-GCM / PBKDF2×200k). Lock re-seals; unlock re-materialises for the session. Auto-lock after 5 min idle (1–120 configurable); 5 wrong tries → 60 s cooldown that survives restarts.
- Passkey (v7): where the platform supports it (macOS/Windows webviews), a fingerprint/PIN gates unlock — proof a human is present. Honest scope: it gates, it doesn't encrypt; the vault password remains the at-rest boundary. Linux upgrade path documented.
- Passwords travel stdin only, never argv, never logged; the seed words are never persisted by the wallet.
Agents pane — give a bot a wallet without fear
The wallet can view and manage every agent account on your loopd: set cap_cents_per_day, watch spend-today, revoke (cut off in ~2 s) or restore. This is the everyday face of the caps story (how it works §3): even a hijacked agent key spends only today's allowance.
Troubleshooting
| Symptom | Fix |
|---|---|
| Wallet opens but balances fail | Services down — bash scripts/status.sh; loopd :8823 must be up. |
| "Set an app password" missing | Vault already set; Settings ▸ vault status shows it. |
| Locked out 60 s | 5 wrong tries — wait, then use your words if the password is truly gone. |
| Passkey prompt never appears | Your platform/webview lacks WebAuthn — the wallet falls back to password-only (graceful by design). |
| GUI behaves differently from the CLI | The wallet shells out to the same qalchat.py — check the CLI for ground truth; report version with the app (v7, 2026-09-11). |
Companions: wallet strategy · Tauri wallet app reference · getting-started · using-chat.