Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

TUI Wallet Usecases

#UsecaseFileDescriptionPersistence
1SetupScreentui/src/screens/setup.rs:32Wallet creation/import wizard (7 sub-steps)Writes seed.enc (keypunkd), writes pre_derived_keys + accounts tables (paypunkd)
2GreetingScreentui/src/screens/greeting.rs:16Initial unlock prompt for existing walletReads seed.enc (keypunkd), writes pre_derived_keys + accounts tables (paypunkd)
3LockScreentui/src/screens/lock.rs:17Re-authentication after auto-lockNone — no-op implementation
4HomeScreentui/src/screens/home.rs:19Account list and main navigationReads accounts table, writes accounts on add
5AssetsScreentui/src/screens/assets.rs:27Asset balance view with Send/Receive/History buttonsReads accounts table; balance from chain RPC
6SendScreentui/src/screens/send.rs:78Multi-step send flow (Form → Review → Sending → Confirm)Reads accounts table; address book persisted to SQLite; signing reads seed.enc
7ReceiveScreentui/src/screens/receive.rs:15Display receiving address + QR codeReads accounts table
8SettingsScreentui/src/screens/settings.rs:21Auto-lock, fiat currency, reveal recovery phraseReads/writes settings table; reveal reads seed.enc via keypunkd
9HelpScreentui/src/screens/help.rs:11Context-sensitive keybinding overlayNone — pure UI overlay

Persistence Layer Summary

keypunkd — Seed Store

  • File: {data_dir}/seed.enc
  • Format: [salt(16B) | nonce(12B) | AES-256-GCM ciphertext]
  • Encryption: Argon2id key derivation + AES-256-GCM
  • Access: Atomic write via seed.enc.tmp + rename; read via std::fs::read

paypunkd — SQLite Database

  • File: {data_dir}/paypunkd.db (plaintext — encryption at rest is planned but not yet implemented)
  • Tables:
    • accounts — id TEXT PK, protocol TEXT, derivation_path TEXT, name TEXT, address TEXT, viewing_key BLOB, created_at INTEGER, birthday_height INTEGER
    • pre_derived_keys — protocol TEXT, account_index INTEGER, viewing_key BLOB, created_at INTEGER DEFAULT (strftime('%s','now')), PRIMARY KEY (protocol, account_index)
    • address_book — id INTEGER PK AUTOINCREMENT, name TEXT, address TEXT UNIQUE, protocol TEXT, created_at INTEGER
    • settings — key TEXT PK, value TEXT
    • signer_state — session_public_key BLOB, created_at INTEGER DEFAULT (strftime('%s','now'))
    • _migrations — version INTEGER PK, applied_at TEXT DEFAULT (datetime('now'))
  • Lock/unlock: is_locked() always returns false — no DB encryption currently implemented. A .wallet_initialized marker file tracks wallet existence.

Address Book

  • Persisted in paypunkd SQLite address_book table via AddAddressBookEntry/GetAddressBook IPC messages

Architecture Layers

TUI Screen  →  RealWalletApi  →  paypunk-api Client  →  IPC (Unix socket)
                                                              ↓
                                                          paypunkd
                                                         ↙        ↘
                                                   SQLite DB    keypunkd (IPC)
                                                                    ↓
                                                               seed.enc (disk)
  • TUI Screen: Ratatui widget with Screen trait — renders UI and handles keyboard input
  • RealWalletApi: tui/src/api/real.rs — implements WalletApi trait, communicates via paypunk-api::Client
  • paypunk-api Client: api/src/client.rs — high-level client wrapping PaypunkService IPC calls
  • paypunkd: paypunkd/src/ — wallet daemon (DB, protocol implementations, orchestration)
  • keypunkd: keypunkd/src/ — key daemon (seed storage, signing, viewing key derivation)