asgayapedia

UX Principles

Purpose: Document the user experience philosophy guiding Asgaya’s design decisions.

Status: Production-proven (Phase 0 - August 2026)
Philosophy: Manual first, automate strategically. User control over convenience.

Core Principle: Manual > Automatic

The guideline: When choosing between manual user control and automatic background operations, default to manual.

Why:

  1. Predictability - User knows exactly when network/blockchain operations happen
  2. Battery efficiency - No background services draining power
  3. Privacy - No unexpected network requests
  4. Simplicity - Fewer moving parts, less to debug
  5. Trust - User sees and controls every action

This is not laziness. Background automation is complex and can be built later. Manual control is the foundation that proves the core flow works.

Principle 1: User Controls Timing

Implementation: All blockchain queries and transactions are user-initiated.

Examples from Production

Balance queries:

User taps "🔄 Update Status" → App queries blockchain → Shows result

NOT:

App polls blockchain every 30s in background → Updates UI automatically

Claim execution:

User reviews parameters → Taps "💰 Claim" → Transaction executes

NOT:

App detects funded covenant → Auto-claims in background → User sees notification

Why manual?

Trade-offs Accepted

Convenience: User must manually check covenant status

Reliability: No missed claims due to background service crashes, no battery drain, no permission issues

For Phase 0: Manual checking is acceptable. One covenant at a time. User expects to monitor.

For scale: If user testing shows manual checking is painful (merchants with 50 covenants/day), THEN consider background monitoring. Not before.

Principle 2: Simplicity First (Phase 0 Philosophy)

Implementation: Minimalist feature set. Prove core flow before adding conveniences.

What Phase 0 Includes

Essential operations:

Essential infrastructure:

That’s it. No extras. No “nice to have” features.

What Phase 0 Excludes

Background services:

Convenience features:

Advanced features:

Why exclude these?

  1. They’re not required to prove the core mechanism works
  2. Each feature adds complexity (more code to debug, more surfaces for bugs)
  3. We don’t know which will actually be useful yet (assumptions ≠ validated pain points)
  4. Phase 0 is about proving viability, not polish

When to Add Features

After Phase 0 proves:

Then observe:

Then automate strategically:

Principle 3: Automate Pain Points, Not Assumptions

The trap: “Users will find X annoying, let’s automate it!”

The method: Ship manual version → Observe actual usage → Identify real friction → Automate proven pain points

Example: Electrum Subscriptions

The assumption: “Users won’t want to manually tap ‘Update Status’ to check covenant balance. Let’s implement Electrum subscriptions for real-time notifications!”

The reality:

The decision:

Result: Simpler implementation, faster to production, can still add subscriptions later if needed.

Example: 5-Second TCP Cooldown

The assumption: “5 seconds is too slow! Users will hate waiting after checking balance!”

The reality:

The decision:

Result: Shipped working implementation. Can optimize later if needed.

Validation Framework

Before automating, ask:

  1. Have we observed this pain point in real usage?
    • ❌ “I think users will find X annoying” → Not validated
    • ✅ “Three test users complained about X” → Validated
  2. What’s the complexity cost?
    • Background service + reconnection logic + battery optimization = High
    • Add a button = Low
  3. What’s the failure mode?
    • Background service crashes → User misses claim → Lost money
    • Manual button doesn’t work → User sees error, retries
  4. Can we test the simple version first?
    • Almost always yes!
  5. What’s the actual usage pattern?
    • Merchant with 50 covenants/day → Automation helps
    • Personal remittance 2x/month → Manual is fine

Default: Ship simple, observe real usage, automate proven pain points.

Principle 4: Transparent Operations

Implementation: User sees what’s happening. No hidden background work.

Status Visibility

Balance checks:

// User sees:
"⏳ Checking balance..."
// Then:
"✅ Funded: 540000 sats"
// Or:
"✅ Claimed (balance: 0)"

TCP cooldown (Phase 0):

Log.d(TAG, "⏳ Waiting 5s for TCP connection cleanup...")
delay(5000)
Log.d(TAG, "✅ TCP connection cleanup complete")

User understands there’s a delay and why.

Transaction Details

Claim covenant UI shows:

User confirms before transaction executes.

NOT hidden: “Claiming…” → Done (user has no idea what just happened)

Error Messages

WebSocket connection fails:

❌ Connection failed: ElectrumClient timeout
Try: Check Fulcrum node is running (192.168.1.100:60003)

NOT: “Error” (what error? what should I do?)

Logging Philosophy

In development: Verbose logging to help debug

In production: Key events logged (connection, transaction broadcast, balance updates)

User sees: Status updates, not raw logs

Principle: User should never wonder “What is the app doing right now?”

Principle 5: Accept UX Trade-offs for Reliability

Core belief: In early phases, reliability > convenience.

Examples of Trade-offs

5-second TCP cooldown:

Manual balance updates:

Copy-paste parameter transport (Telegram):

Phase 0 priority ranking:

  1. Correctness - Does it work? (covenant math, buffer distribution)
  2. Reliability - Does it work consistently? (connection management, error handling)
  3. Security - Is it safe? (private key handling, transaction validation)
  4. Simplicity - Can we understand and debug it? (minimal complexity)
  5. Performance - Is it fast enough? (5-second delay acceptable)
  6. Convenience - Is it pleasant to use? (nice to have, optimize later)

This ranking is intentional. Premature optimization of convenience before proving reliability is backwards.

Principle 6: Progressive Enhancement

Implementation: Start with proven foundation, add features incrementally.

Phase 0: Prove Core Flow

Goal: Demonstrate guaranteed-value BCH transfers work

Features:

Success criteria:

Status: ✅ Achieved August 10, 2026

Phase 1: Merchant Cash-Out Flow (Next)

Goal: Enable seller-funded covenants (liquidity provision)

New features:

Success criteria:

What NOT to add yet:

Why: Prove seller-funded flow works before optimizing it.

Phase 2+: Scale & Polish (Future)

Goal: Handle higher volume, improve UX based on real feedback

Potential features (validated pain points only):

Decision framework:

  1. What pain points did Phase 0/1 reveal?
  2. What do actual users struggle with?
  3. What automation provides measurable improvement?

Not guessing. Observing.

Anti-Patterns to Avoid

These violate Asgaya UX principles:

Anti-Pattern 1: Premature Automation

Bad:

// Phase 0 implementation
class CovenantMonitorService : Service() {
    // Polls blockchain every 30s
    // Auto-claims when funded
    // Sends push notifications
}

Why bad:

Good:

// Phase 0 implementation
button.setOnClickListener {
    // User taps button
    checkBalance()
}

Why good:

Anti-Pattern 2: Hidden Operations

Bad:

// Silently queries blockchain every time fragment appears
override fun onResume() {
    lifecycleScope.launch {
        updateBalances() // No user feedback!
    }
}

Why bad:

Good:

// User explicitly requests update
updateButton.setOnClickListener {
    statusText.text = "⏳ Checking balance..."
    lifecycleScope.launch {
        val balance = checkBalance()
        statusText.text = "✅ Balance: $balance sats"
    }
}

Why good:

Anti-Pattern 3: Feature Creep Before Validation

Bad:

Phase 0 scope:
- Core covenant flow
- Batch claiming
- QR code sharing  
- Address book
- Analytics dashboard
- Auto-refund scheduling
- Exchange rate alerts
- Transaction history search

Why bad:

Good:

Phase 0 scope:
- Core covenant flow (create, fund, claim, refund)

Phase 1 scope (after Phase 0 proven):
- Seller-funded flow

Phase 2 scope (after observing Phase 1 usage):
- Features that address observed pain points

Why good:

Anti-Pattern 4: Optimizing Before Measuring

Bad:

// Replace 5-second cooldown with connection pooling
class ConnectionPool {
    private val tcpConnections = mutableListOf<ElectrumClient>()
    private val wsConnections = mutableListOf<ElectrumWebSocket>()
    
    // 200 lines of pooling logic
    // Not tested in production yet!
}

Why bad:

Good:

// Phase 0: Accept 5-second delay
delay(5000) // TCP cooldown - documented workaround

// After Phase 1: Measure actual pain
// - Do users complain about delay?
// - How often do they update balance?
// - Is delay noticeable in real usage?

// THEN decide: Is connection pooling worth complexity?

Why good:

Design Process

How to apply these principles when making UX decisions:

Step 1: What’s the simplest version that works?

Example: Parameter sharing between devices

Options:

  1. Manual copy-paste (simplest)
  2. QR code scanning (medium)
  3. NFC tap (complex)
  4. Bluetooth pairing (most complex)

Phase 0 choice: Manual copy-paste via Telegram

Why: Works immediately, no custom UI needed, can test parameter format

Step 2: What’s the failure mode?

Manual copy-paste:

QR code:

For Phase 0: Manual is safer (fewer failure modes)

Step 3: What’s the complexity cost?

Manual: Zero new code (use existing clipboard/Telegram)

QR code: QR generation library, camera integration, permission handling, scan UI

For Phase 0: Manual wins (lower cost)

Step 4: Can we validate with simple version first?

Yes! Ship copy-paste, see if users struggle. If they do, THEN add QR codes.

Result: Ship simple, iterate based on feedback.

Measuring UX Success (Phase 0)

How do we know if UX principles are working?

Success Metrics

1. Core flow completion rate

2. Error recovery rate

3. Time to completion

4. User confusion points

5. Reliability

What We’re NOT Measuring (Phase 0)

Convenience metrics:

Why not: These matter at scale, not for proving viability.

Future UX Evolution

Where this philosophy might change:

At Scale (Post Phase 0)

If merchants process 50 covenants/day:

If personal users send 2 remittances/month:

Different use cases may need different UX!

With Nostr Integration (Phase 1+)

Nostr coordination layer enables:

Still manual-first: User initiates Nostr DM, not automatic background syncing.

Mobile-First Constraints

Asgaya is mobile-first, which reinforces manual philosophy:

Mobile reality: Manual, user-initiated operations are more reliable than background automation.

Summary

Asgaya UX principles in one sentence:

“Ship the simplest version that proves the mechanism works, observe real usage, then automate proven pain points strategically.”

Core principles:

  1. Manual > Automatic - User controls timing, no background surprises
  2. Simplicity First - Phase 0 is minimalist, add features incrementally
  3. Automate Pain Points, Not Assumptions - Observe before automating
  4. Transparent Operations - User sees what’s happening
  5. Accept UX Trade-offs for Reliability - Correctness > Convenience in early phases
  6. Progressive Enhancement - Build on validated foundation

This is intentional. These principles got us to production (August 10, 2026) with a working, reliable covenant flow.

What’s next: Apply same principles to Phase 1 (merchant flow). Prove it works before optimizing it.

Status: Production-validated
Last Updated: 2026-08-13
Evidence: Phase 0 core flow working, documented, reproducible

Implementation:

Design Constraints:

User Journeys:

This site is open source. Improve this page.