asgayapedia

RS081: Multi-Wallet Management Patterns in Production BCH Wallets

Date: 2026-08-02
Type: UX Research + Technical Architecture
Status: Implemented (August 2-3, 2026)
Phase: Phase 0 - Wallet UI Enhancement

Executive Summary

Goal: Research how production BCH wallets handle multiple wallet/account management to inform Asgaya’s wallet switching UI design.

Key Findings:

  1. HD Wallet Standard (BIP44) - Industry standard uses account-level derivation (m/44'/145'/account') for multiple wallets from single seed
  2. UX Pattern Consensus - MetaMask, Trust Wallet, and major wallets use top-center account selector with dropdown list
  3. Bitcoin.com Architecture - Proven implementation using Copay/Bitcore Wallet Service
  4. Storage Strategy - Local encrypted private keys, BIP39 mnemonic backup, BIP32 HD derivation

Asgaya Implementation:

Status: ✅ Implemented August 2-3, 2026. Multi-wallet switching working with instant balance updates.

See: Wallet Component for complete implementation documentation.

Research Context

Problem: Asgaya needs multi-wallet switching to enable:

  1. Fast testing of covenant flows (sender → recipient → merchant on one device)
  2. Role-based wallet management (sender, recipient, merchant, oracle)
  3. Single-device development workflow

Research Question: How do production BCH wallets implement multi-wallet/account management, and what UX patterns work best?

Key Findings

1. HD Wallet Standard (BIP32/39/44)

Sources:

Standard Hierarchy:

m / purpose' / coin_type' / account' / change / address_index

For Bitcoin Cash:
m / 44' / 145' / account' / 0 / 0
         └─BCH──┘ └─account─┘

Account Switching:

Key Benefit: Single seed phrase recovers ALL accounts. User can switch between wallets while maintaining single backup.

2. UX Patterns - Account Switching

Sources:

MetaMask Mobile Pattern:

┌─────────────────────────────────┐
│  [☰]    Account 1 ▼    [⚙️]    │  ← Tap to open selector
│         └─Selector─┘             │
├─────────────────────────────────┤
│  Balance: 0.5 ETH                │
│  ≈ $1,234.56                     │
└─────────────────────────────────┘

Trust Wallet Pattern:

┌─────────────────────────────────┐
│  💼 My Wallets ▼                │  ← Wallet selector
├─────────────────────────────────┤
│  Balance: $1,234.56              │
└─────────────────────────────────┘

Common UX Principles:

  1. Top-center placement - Account selector at top of home screen
  2. Current account name - Shows active wallet/account
  3. Dropdown/modal - Tap to see all accounts
  4. Visual indicator - Checkmark shows active account
  5. Quick add - “+ Add account” option in selector
  6. Truncated addresses - Show first/last chars (0x1234…5678)
  7. Balance preview - Optional balance shown in selector list

3. Bitcoin.com Wallet Architecture

Source: Bitcoin.com Wallet GitHub

Key Architecture:

Multi-Wallet Implementation:

Key Insight: Uses Bitcore Wallet Service as abstraction layer between app and blockchain, enabling clean separation of wallet logic from UI.

4. Security & Storage Patterns

Key Management:

Storage Options Evaluated:

Option A: HD Wallet Only

Option B: Imported Keys Only

Option C: Hybrid (RECOMMENDED & IMPLEMENTED)

Asgaya Implementation (August 2026)

Architecture Decision: Hybrid Approach

Data Model:

sealed class WalletSource {
    data class HDDerived(val accountIndex: Int)  // From BIP39 seed (Phase 1+)
    data class ImportedKey(val wif: String)      // From covenant-params (Phase 0)
}

data class Wallet(
    val id: String,
    val label: String,
    val role: WalletRole,  // SENDER, RECIPIENT, MERCHANT
    val source: WalletSource,
    val address: String,
    val publicKey: String,
    val isActive: Boolean = false
)

Benefits:

UI Implementation

Asgaya Wallet Selector:

┌─────────────────────────────────┐
│  [☰] Asgaya    💼 Sender ▼ [⚙️] │  ← Tap to switch
│                  └─────┘          │
├─────────────────────────────────┤
│  Balance: 0.05234 BCH            │
│  ≈ €52.34                        │
└─────────────────────────────────┘

Selector Dialog:

┌─────────────────────────────────┐
│  Select Wallet                   │
├─────────────────────────────────┤
│  ✓ 📤 Sender                     │  ← Active (checkmark)
│     bchtest:qrw5nu...            │
│     0.052 BCH                    │
│                                  │
│    📥 Recipient (Isabel)         │
│     bchtest:qq2uxg...            │
│     0.007 BCH                    │
│                                  │
│    🏪 Merchant (Bob)             │
│     bchtest:qz4lla...            │
│     0.000 BCH                    │
└─────────────────────────────────┘

Role Icons:

Note: Role labels are testing convenience only, not enforced. Production users can label wallets however they want (“Merchant hot wallet”, “Personal savings”, “BCH seller funding”, etc.)

Testing Workflow Enabled

Covenant Claim Test (All on One Device):

1. Switch to "Sender" wallet 💼
2. Fund covenant with 0.00749 BCH
3. Send Telegram notification
4. Switch to "Recipient (Isabel)" wallet 💼
5. Tap "Claim Now" → WebView executes claim
6. Success! Balance updates instantly

Impact: Complete covenant testing on single device with instant role switching. Development velocity increased significantly.

Production Impact

Immediate Benefits (Phase 0):

  1. ✅ Faster testing - Switch between roles instantly
  2. ✅ Better UX - Proven wallet selector pattern
  3. ✅ Single device - Complete covenant testing on one phone
  4. ✅ Real wallets - Actually sign transactions with different keys

Long-term Benefits (Phase 1+):

  1. User feature - Some users need multiple wallets (personal, business, different countries)
  2. Role separation - Clear visual distinction between sender/recipient/merchant roles
  3. Standard compliance - BIP32/39/44 means compatible with other wallets
  4. Future-proof - Can add hardware wallet support, multi-sig, etc.

Security Considerations:

Alternative Approaches Considered

Option 1: Separate Apps

Option 2: Contact-Based Switching (No Real Wallets)

Option 3: HD Wallet ONLY

Option 4: Imported Keys ONLY

Option 5: Hybrid (HD + Imported) ✅ IMPLEMENTED

References

Wallet Architecture:

BIP Standards:

UX Patterns:

Bitcoin Cash Specifics:

Implementation:

User Journeys:

Design Decisions:

Status: ✅ Research Complete → Implementation Complete (August 2-3, 2026)
Implementation Time: ~90 minutes (as estimated)
Result: Multi-wallet switching working with instant balance updates, 3 pre-seeded test wallets

This site is open source. Improve this page.