element-x-ada/BLOCKERS.md

BLOCKERS.md - Phase 1 Implementation Status

Task 1: Module Scaffolding ✅ COMPLETE

Completed

• ✅ Module structure created (api/impl/test)
• ✅ Metro DI setup following Element X patterns
• ✅ WalletEntryPoint and WalletState APIs defined
• ✅ PaymentFlowNode placeholder with Appyx navigation
• ✅ FakeWalletEntryPoint for testing
• ✅ Cardano client library dependencies added
• ✅ ProGuard rules configured
• ✅ Basic unit tests added
• ✅ Pushed to Gitea phase1-dev branch

---

Task 2: Key Generation + Storage ✅ COMPLETE

Completed

• ✅ CardanoNetworkConfig.kt - Single object for testnet/mainnet config swap

  • Currently configured for TESTNET (preprod)
  • Change NETWORK to CardanoNetwork.MAINNET for production
  • All derived values (Koios URL, explorer URL, address prefix) auto-switch

• ✅ CardanoKeyStorage (interface + implementation)

  • Per-session wallet isolation (key alias: cardano_wallet_{sessionId})
  • 24-word BIP-39 mnemonic generation using cardano-client-lib
  • AES-GCM-256 encryption with Android Keystore-backed key
  • setUserAuthenticationRequired(true) - biometric/PIN for every operation
  • setUserAuthenticationValidityDurationSeconds(-1) - no grace period
  • setInvalidatedByBiometricEnrollment(true) - invalidate on biometric change
  • Methods: generateWallet, importWallet, getMnemonic, getBaseAddress, getStakeAddress, deleteWallet

• ✅ CardanoWalletManager (interface + implementation)

  • Key derivation using CIP-1852 via cardano-client-lib's Account class
  • Path m/1852'/1815'/0'/0/0 for external receiving address
  • Path m/1852'/1815'/0'/2/0 for staking key
  • Shelley base address generation (payment + staking key hash)
  • Uses CardanoNetworkConfig for network selection
  • Exposes: getAddress(sessionId), getStakeAddress(sessionId), getSpendingKey(sessionId)

• ✅ SeedPhraseManager (interface + implementation)

  • 24-word mnemonic generation (256-bit entropy)
  • Support for 12/15/18/21/24 word counts
  • BIP-39 validation (checksum + wordlist)
  • Word suggestions for autocomplete
  • Normalization (whitespace, case)
  • ⚠️ UI must apply FLAG_SECURE when displaying seed phrases (documented)

• ✅ FakeCardanoKeyStorage for testing

• ✅ Unit tests for SeedPhraseManager, CardanoNetworkConfig, CardanoWalletManager

Decisions Made (per instructions)

• Wallet scope: PER SESSION (each Matrix account has its own wallet)
• Biometric change: INVALIDATE key + require wallet re-import/creation
• Network: TESTNET (preprod) - single config constant for easy mainnet swap

Not Verified (No Android SDK in build environment)

• ⚠️ Compilation with ./gradlew :features:wallet:impl:assemble
• ⚠️ Unit tests with ./gradlew :features:wallet:impl:test
• ⚠️ ktlint compliance
• ⚠️ Actual Android Keystore behavior (requires device/emulator)
• ⚠️ Biometric prompt integration (requires Activity context)

Security Notes

1. Mnemonic never stored in plaintext - Always encrypted with Keystore key
2. Key material cleared after use - ByteArray.fill(0) called where possible
3. Per-session isolation - Different Matrix accounts cannot access each other's wallets
4. Biometric invalidation - If user adds/removes fingerprints, wallet key becomes invalid
5. No screenshots - UI must apply FLAG_SECURE when showing seed phrase

---

Task 3: Koios Client ✅ COMPLETE

Completed

• ✅ CardanoClient.kt interface in api/ module:

  • getBalance(address: String): Result<Long> — balance in lovelace
  • getUtxos(address: String): Result<List<Utxo>> — unspent outputs
  • submitTx(signedTxCbor: String): Result<String> — returns tx hash
  • getTxStatus(txHash: String): Result<TxStatus> — PENDING/CONFIRMED/FAILED

• ✅ Data models in api/:

  • Utxo.kt — txHash, outputIndex, amount, address
  • TxStatus.kt — enum PENDING/CONFIRMED/FAILED
  • CardanoException.kt — typed exceptions (NetworkException, RateLimitException, InvalidAddressException, TransactionNotFoundException, SubmissionFailedException, InsufficientFundsException, ApiException)

• ✅ KoiosCardanoClient.kt implementation:

  • Uses BackendFactory.getKoiosBackendService() from cardano-client-lib
  • Testnet URL: https://preprod.koios.rest/api/v1 (via CardanoNetworkConfig)
  • Mainnet URL: https://api.koios.rest/api/v1 (via CardanoNetworkConfig)
  • 3 retries with exponential backoff (1s → 2s → 4s, max 10s)
  • Basic rate limiting (100ms min between requests for Koios 100 req/10s limit)
  • DI: @ContributesBinding(SessionScope::class)
  • Error parsing: 429 → RateLimitException, 5xx → NetworkException, etc.

• ✅ FakeCardanoClient.kt for testing:

  • Configurable balances, UTxOs, transaction statuses
  • Error simulation (network errors, rate limits, submit failures)
  • Transaction lifecycle simulation (pending → confirmed → failed)
  • Call counters for test verification
  • Helper: setupWallet(address, balance) creates realistic UTxO set

• ✅ KoiosCardanoClientTest.kt — 15+ unit tests:

  • getBalance success, unknown address, network error, rate limit
  • getUtxos success, empty result
  • submitTx success, failure
  • getTxStatus pending, confirmed, failed
  • reset/state management

• ✅ CardanoWalletManager updated to use CardanoClient:

  • refreshBalance() now fetches real balance via Koios
  • Updates WalletState with lovelace + formatted ADA string

Design Notes

• No API key required — Koios public API is free
• Network config centralized — Change CardanoNetworkConfig.NETWORK to swap testnet/mainnet
• Hex CBOR for submitTx — Accepts hex-encoded signed transaction bytes
• UTxO pagination — Limited to first 100 UTxOs (sufficient for typical wallets)

Potential Issues

• ⚠️ getTxStatus returns PENDING for unknown hashes (could be never-submitted or truly pending)
• ⚠️ Koios rate limit (100 req/10s) may need adjustment for heavy usage patterns
• ⚠️ No getProtocolParameters yet (needed for Task 4 fee calculation)

---

Task 4-6: See PHASE1-PLAN.md

---

Task 7: Timeline Payment Card ✅ COMPLETE

Completed

• ✅ PaymentCardStatus.kt — Enum for PENDING/CONFIRMED/FAILED states
• ✅ TimelineItemPaymentContent.kt — Data class implementing TimelineItemEventContent
  • amountLovelace, addresses, txHash, status, network, isSentByMe
  • Computed properties: amountAda, isTestnet, truncatedTxHash, explorerUrl
  • Companion formatAda() helper
• ✅ TimelineItemPaymentView.kt — Compose UI for payment card
  • Cardano icon (₳ symbol)
  • Amount in ADA (formatted from lovelace)
  • Status chip with spinner (pending), checkmark (confirmed), X (failed)
  • Testnet badge when applicable
  • Truncated tx hash (tappable → CardanoScan)
  • View on explorer link for confirmed transactions
  • @PreviewsDayNight with multiple preview states
• ✅ TimelineItemPaymentContentTest.kt — Unit tests for content model
• ✅ Integration with TimelineItemEventContentView.kt

Design Notes

• Payment cards use different colors for sent (primary) vs received (surface)
• Explorer URLs: preprod.cardanoscan.io for testnet, cardanoscan.io for mainnet
• Tx hash truncated to first 8 + last 8 chars for display

---

Task 8: Raw Event Handling ✅ COMPLETE (UPGRADED)

✅ RESOLVED: SDK Raw Event API

Previous blocker: Matrix Rust SDK did not expose raw event sending or raw JSON access.

Resolution: The SDK (version 26.03.24) now provides:

• Timeline.sendRaw(eventType: String, content: String) — Sends custom event types
• MsgLikeKind.Other with eventType field — Receives custom events
• TimelineItemDebugInfo.originalJson — Access to raw event JSON via debug info provider

Implementation updated to use proper raw events instead of text markers.

Completed

• ✅ PaymentEventSender.kt — Interface for sending payment events
• ✅ DefaultPaymentEventSender.kt — Implementation using raw events
  • Uses timeline.sendRaw(eventType, content) to send custom events
  • Event type: co.sulkta.payment.request (reverse-domain format)
  • Status updates: co.sulkta.payment.status
  • No text marker hack — proper Matrix custom events
• ✅ TimelineItemContentPaymentFactory.kt — Parser for payment events
  • isPaymentEventType(eventType) — Checks for payment event type
  • isStatusUpdateEventType(eventType) — Checks for status update type
  • createFromRaw(json, isSentByMe) — Parses raw JSON from custom events
  • Supports both camelCase and snake_case field names
  • Graceful error handling — returns null on malformed JSON
• ✅ TimelineEventContentMapper.kt — Maps MsgLikeKind.Other to CustomEventContent
• ✅ TimelineItemContentFactory.kt — Handles CustomEventContent for payments
  • Gets raw JSON via timelineItemDebugInfoProvider().originalJson
  • Delegates to paymentFactory for payment event types
• ✅ CustomEventContent.kt — New EventContent type for custom events
• ✅ Timeline.sendRaw() — Added to Timeline interface and RustTimeline implementation
• ✅ FakePaymentEventSender.kt — Test fake
• ✅ TimelineItemContentPaymentFactoryTest.kt — Updated unit tests

m.replace Status Updates

Decision: Status updates are sent as separate events of type co.sulkta.payment.status.

Future improvement: When SDK exposes event relations, refactor to use m.replace for cleaner status update thread.

Benefits of Raw Event Approach

• ✅ Proper Matrix protocol compliance (custom event types, not hacked text)
• ✅ Non-wallet clients see "Unknown event" instead of JSON-in-text
• ✅ Clean separation of payment events from regular messages
• ✅ Events won't be indexed by message search
• ✅ No message length limits concern

---

Known Issues

Issue 1: Biometric Prompt Activity Context

The CardanoKeyStorageImpl uses setUserAuthenticationRequired(true) which will cause UserNotAuthenticatedException when accessing the key. The biometric prompt UI must be triggered from an Activity/Fragment context before calling getMnemonic(), getSpendingKey(), etc.

Solution: Task 6 (Payment Flow UI) must call BiometricPrompt before invoking storage operations.

Issue 2: KeyPermanentlyInvalidatedException

If user changes biometric enrollment, the Keystore key is invalidated. Current behavior: throws exception, user must delete and recreate wallet.

Enhancement (future): Show user-friendly message explaining why wallet became invalid and offer to re-import.

---

Last updated: 2026-03-27 - Task 2 complete