#69 Enhancement: Display QR codes for deposit addresses

[andycreed0x]

Purpose

Generate and return a PNG file of the QR code for every deposit address and invoice the agent produces, so users can scan instead of copy-paste.
Closes #69 Enhancement: Display QR codes for deposit addresses.

Description

The agent previously returned addresses/invoices as plain text. This PR adds a generate_qr() helper that saves a PNG QR to ~/.aqua/qr/ and returns its absolute path as qr_code_path in the tool result. The system prompt is updated to instruct the agent to always surface the image. QR generation is best-effort. if it fails, the address/invoice is still returned along with a qr_error field (no silent fallbacks).

A reviewer-caught fund-loss hazard was also addressed: SideShift shifts on memo-required chains (BNB, etc.) now include a qr_warning because the QR encodes only the deposit address — the memo must be entered manually.

Main Changes

• ✨ Add generate_qr(data, output_dir, filename=None) to src/aqua/qr.py — atomic write (tempfile → fsync → chmod 0o600 → os.replace), content-addressed filename qr_<sha256[:16]>.png
• ✨ Add _attach_deposit_qr() helper in tools.py — shared seam wired into all 5 receive surfaces with best-effort error handling
• ✨ Wire QR into btc_address, lw_address, lightning_receive, changelly_receive, sideshift_receive — each now returns qr_code_path
• ⚡️ BOLT11 invoices encoded as uppercase in the QR (alphanumeric mode → smaller/denser code; case-insensitive so round-trip is unaffected)
• 🔒️ Add qr_warning for SideShift memo-based chains — scanning the QR alone omits the memo and can cause loss of funds
• 🏗️ Add Storage.qr_dir (~/.aqua/qr/, 0o700) following existing ~/.aqua layout invariants
• 📝 Update server.py tool descriptions and system prompt with a "QR CODES" guidance block (mirrors Pix precedent — description changes alone don't drive display)
• ✅ Add 27 new tests: generate_qr unit tests (round-trip via real zxing decoder, perms, atomicity, idempotency) + TestDepositQr wiring tests (including memo-warning and bolt11 transform)
• ➕ Promote qrcode[pil]>=7.0 from dev extras to runtime dependencies (imported by runtime module)

⚠️ Breaking Changes

None. qr_code_path is an additive field. On QR failure, qr_error is set and the address/invoice is always returned.

Limitation: qr_code_path is a server-side absolute path. Display depends on the MCP client being able to render local file paths as images (works in Claude Code). For guaranteed inline display on remote/mobile clients, ImageContent (embedded PNG bytes) is the plan-B — not included in this PR per scope.

Checklist

• No hardcoded values
• Added/updated tests (27 new tests, 856 passed / 25 skipped)
• Added/updated relevant documentation (if necessary)

[marinate305]

This is exactly what we identified as needed during MCP testing — great to see QR codes wired into all 5 receive surfaces. The qr_warning for memo-required chains is a smart safety addition. The path-based limitation is noted but acceptable for now. Approving.