📖 Unfamiliar terms? See the glossary for definitions.
Purpose: Index of Asgaya client implementation docs (Android-first, platform-agnostic architecture)
Status: Phase 0 in progress — Core covenant flow production-proven (all paths validated on Pi-chan July-Aug 2026; first inter-device claim August 10, 2026)
Asgaya implements peer-to-peer Bitcoin Cash remittances with no backend servers:
Core thesis: Remittances are the funnel to merchants. The covenant’s merchantCashout path enables cash pickup, making Asgaya a permissionless merchant acquisition system.
Key principle: Any competent developer (not blockchain expert) can build an Asgaya client from these docs.
Pragmatic approach (Jun-Aug 2026):
Note: This philosophy emerged from BizumParser work and WebView pivot. Future contributors (or AI in fresh context) benefit from understanding the pragmatic, incremental approach that got us to production.
| Phase | Definition | Status |
|---|---|---|
| Phase 0 | MVP in development (covenant flow working, integration ongoing) | 🔴 In progress |
| Phase 0+ | Features added during testing (cheap UX/reliability wins) | 🔵 Opportunistic |
| Phase 1+ | Post-MVP enhancements based on observed behavior | 🟢 Future |
Phase 0 MVP Definition: Full value proposition working end-to-end:
merchantCashoutProduction-proven components:
| Component | What It Does | Status | Doc |
|---|---|---|---|
| Multi-Wallet | Sender/recipient/merchant wallet switching, Room persistence | ✅ Working | wallet.md |
| CovenantWebView | Kotlin ↔ JS bridge, CashScript SDK integration, P2SH32 address generation | ✅ Working (v0.2 hybrid: compute-only) | webview-covenant-bridge.md |
| CovenantBuildService | v0.2: Kotlin network ops (UTXO fetch + broadcast, native TCP) | ✅ Working | webview-covenant-bridge.md |
| ElectrumClient | Balance queries, transaction broadcast, UTXO management | ✅ Working | connection-management-patterns.md |
| NotificationListener | Bank-notification parsing (auto-fund); coordination is Nostr (NIP-17) — Telegram = fallback | ✅ Working | notification-bot.md |
| Connection Management | TCP cooldown (5s after balance query), WebSocket cleanup, manual updates | ✅ Working (v0.2: WebSocket only for brief UTXO fetch) | connection-management-patterns.md |
| SendViewModel | v0.2: viewModelScope transaction state, pending_transactions DB, rebroadcast, background confirmation (RS083) | ✅ Working | state-management.md |
Covenant v2.6: All 5 spending paths implemented (claim, merchantCashout, refund, abort, sellerRecoverBuffer); v2.5 validated on chipnet, abort on testnet3 (Aug 15)
v0.2 hybrid architecture (Aug 20-21): All 4 covenant operations (CREATE/REFUND/CLAIM/ABORT) now build in the WebView and broadcast from Kotlin. WebView is compute-only. Multi-device reliability restored (the WebSocket connection-accumulation bug is eliminated at the root).
Evidence: First inter-device claim August 10, 2026 (TXID: 193c3c9e5287e13cc56e1401aed55de34db9a375312e052807aea060e58e3d96)
Navigation (2026-10): the app is organised as Home · Market · Trade. Home shows the balance plus the active remittance and Activity/History; Market is the bulletin board as a first-class tab — Buy/Sell, filter by asset and payment method, sort by fee — where a seller posts and re-prices an ad; Trade holds the seller/merchant surfaces. Advanced mode now gates the Trade tab only (one Home for everyone).
See complete flow: claim-flow-end-to-end.md
| Feature | Status | Notes |
|---|---|---|
| Multi-wallet management | ✅ Done | Room database, WalletManager, reactive UI |
| Covenant v2.6 (5 paths) | ✅ Done | All paths validated (v2.5 on chipnet, abort on testnet3) |
| WebView + CashScript SDK | ✅ Done | v0.2 hybrid: compute-only (build/sign), broadcast in Kotlin |
| ElectrumClient (balance/broadcast) | ✅ Done | TCP + WebSocket support |
| Nostr coordination (NIP-17) | ✅ Done | Primary transport; Telegram = test/fallback |
| Connection management patterns | ✅ Done | TCP cooldown, cleanup, manual updates |
| Self-funded sender flow | ✅ Done | Also a real future use case (BCH stable, B2B, CEX savings) |
| v0.2 hybrid (build + Kotlin broadcast) | ✅ Done | CREATE/REFUND/CLAIM/ABORT all hybrid (Aug 20-21) |
| Seller auto-funding (cash-in-person) | ✅ E2E-proven | Sender creates unfunded (funderPubkey=seller) → seller verifies funderPubkey → confirms cash in Trade tab → funds. 4-device E2E Sep 8 |
| Refund (funder≠sender) | ✅ E2E-proven | Sender refunds seller-funded covenant; buffer → seller automatically (Sep 8) |
| Nostr coordination (DM) | ✅ Done | NIP-17 gift-wrapped DMs (NIP-44) via OkHttp; works on cell data. Telegram is now fallback only |
| Bulletin board | ✅ Working (Phase 0) | Nostr (NIP-99) discovery — signed listings cached locally; on-chain anchor = Phase 0+ |
| Cash Accounts | ✅ Registered (testnet) | Real name#number as the payment reference (the bank-notification match key); registered on testnet |
| Merchant cash-out flow | ✅ DONE on-chain | Merchant-first, TXID 05301369... (Sep 1, 2026); merchant role needs no Telegram (QR/paste, tablet-tested) |
| Market tab (the board) | ✅ Working | The bulletin board as a first-class tab: Buy/Sell, filter by asset · payment method, sort by fee; a seller posts and re-prices an ad (Oct 10) |
| Card in person | ✅ Working | A second physical rail (alongside cash in person): a Settings toggle + a publish chip + method-specific instructions (Oct 11) |
| First BCH seller (Suso) | 🔨 Needed | MVP validation requires real seller |
| Feature | Why 0+ | Notes |
|---|---|---|
| Seed phrase backup | Cheap UX win | BIP39 HD wallets, 12-word recovery |
| Seller device health | Already built! | RS072/RS075 DeviceHealthMonitor.kt exists; needs integration + bulletin board ranking |
| Stability layer (H€/HAu) | Retention incentive | Planned (Phase 1+) — design settled; build + legal review pending (stability-layer.md) |
| Kraken API | Volume dependent | Manual/mining covers Phase 0; automate when needed |
| Feature | Why defer | Notes |
|---|---|---|
| Offline-first | Can wait | Online-only acceptable for MVP |
| Own Nostr relay | Operational burden | Public relays sufficient; revisit if reliability issues |
| Cross-border expansion | Progressive rollout | Spain→Venezuela first, then PagoMóvil/M-Pesa |
| Multi-covenant batching | Optimization | Not needed at MVP scale |
claim-flow-end-to-end.md ✅
Complete August 10 flow, architecture decisions, production evidence
connection-management-patterns.md ✅
TCP cooldown, WebSocket cleanup, manual updates, seller resolution notifications (production-proven Aug 8-10)
webview-covenant-bridge.md ✅
Kotlin ↔ JavaScript bridge, CashScript SDK bundling, Webpack config (4 claims + 3 refunds validated)
3b. merchant-cashout-flow.md ✅
Merchant-first cashout (merchant pre-signs, recipient co-signs); first on-chain transaction Sep 1, 2026
asgaya-trinity.md ✅
Create → Send → Claim architecture, scope boundary (wallet not infrastructure)
two-layer-architecture.md ✅
Covenant (permissionless) vs Client (opinionated) separation principle
wallet.md 🔨
Multi-wallet ✅, Cash Account registration ✅ (real, testnet), HD derivation (Phase 0+)
notification-bot.md 🔨
Telegram parsing ✅, bank notification parsing (Phase 0+), market price subscription (Phase 0+)
state-management.md 🔨
Wallet storage ✅ (Room + WalletEntity), covenant tracking (Phase 0+), bulletin board cache (Phase 0+)
Legend:
Phase 0 challenges (learned during Aug 2026 work):
finally blocks prevent leakssend() vs build(): CashScript’s send() polls for confirmation up to 10 min; build() returns signed hex locally. Always build() + Kotlin broadcasttx_hash/tx_pos; CashScript SDK uses txid/vout. Mixing them crashes with “reading ‘length’” (Aug 21)Phase 0+ challenges (deferred):
name#number format disambiguates ✅ (implemented)See component docs for detailed solutions.
Phase 0 (in use):
192.168.1.100 (60001 TCP, 60003 WS), testnet3; Phase 0+ adds redundancy (3-5 servers)Phase 0+ (planned):
See component docs for integration details.
Conceptual (read first):
Implementation (covenants):
Research:
Media (Phase 0+ content refresh needed):
Phase 0 success (August 10, 2026): ✅ Achieved
Full MVP success (Phase 0 ongoing): 🔨 In Progress
Documentation success: ✅
| 🏠 Home | ↑ Implementation | 📖 Glossary |
This section: Android App
Related: Covenants | The Mechanism
Last updated: 2026-10-12 (Market tab, card rail, multi-currency)
Status: Phase 0 in progress (covenant flow proven, integration ongoing)
Evidence: First inter-device claim TXID 193c3c9e5287e13cc56e1401aed55de34db9a375312e052807aea060e58e3d96