105 KiB
105 KiB
Element X ADA Wallet — Phase 1 Implementation Plan
Date: 2026-03-27 (Updated)
Author: Kayos
Target: Local-only MVP — /pay 10 ADA @jacob end-to-end
Repo: Sulkta-Coop/element-x-ada
Overview
Phase 1 delivers a functional Cardano lite wallet embedded in Element X Android:
- User types
/pay 10 ADA @jacobin a DM - Confirmation screen opens with amount + recipient
- Biometric authentication triggers
- Transaction is signed and submitted via Koios
- Payment card renders in timeline for both parties
- Recipient taps to view tx on CardanoScan
Constraints:
- Local-only (no SSSS sync — Phase 2)
- Keys stored in Android Keystore
- Koios for chain queries (no API key needed)
cardano-client-lib(pure Java, no JNI)- Custom Matrix event:
m.payment.cardano(sent via raw event API)
Dependency Graph
┌─────────────────────────────────────────────────────────────────────┐
│ BUILD ORDER │
└─────────────────────────────────────────────────────────────────────┘
Task 1: Module Scaffolding
│
├──────────────────┬──────────────────┐
▼ ▼ ▼
Task 2: Key Storage Task 3: Koios Task 8: SDK Extension
│ Client │
└────────┬─────────┘ │
▼ │
Task 4: Transaction Builder │
│ │
├─────────────────────────────────┘
▼
Task 5: Slash Command Parser
│
▼
Task 6: Payment Flow UI
│
▼
Task 7: Payment Card Timeline
Task 1: features/wallet/ Module Scaffolding
Blocks: Tasks 2, 3, 4, 5, 6, 7
Blocked by: Nothing
Effort: 1 day
Acceptance criteria:
- Module compiles with
./gradlew :features:wallet:impl:assemble - DI module loads without errors
- WalletEntryPoint accessible from app module
- Unit test infrastructure works (
./gradlew :features:wallet:impl:test)
Files
New: features/wallet/api/build.gradle.kts
plugins {
id("io.element.android-library")
}
android {
namespace = "io.element.android.features.wallet.api"
}
dependencies {
implementation(projects.libraries.architecture)
implementation(projects.libraries.matrix.api)
implementation(projects.libraries.designsystem)
}
New: features/wallet/impl/build.gradle.kts
plugins {
id("io.element.android-compose-library")
alias(libs.plugins.anvil)
alias(libs.plugins.kotlin.serialization)
}
android {
namespace = "io.element.android.features.wallet.impl"
}
anvil {
generateDaggerFactories.set(true)
}
dependencies {
implementation(projects.features.wallet.api)
implementation(projects.libraries.architecture)
implementation(projects.libraries.matrix.api)
implementation(projects.libraries.matrix.impl)
implementation(projects.libraries.designsystem)
implementation(projects.libraries.cryptography.api)
implementation(projects.libraries.cryptography.impl)
implementation(projects.libraries.core)
implementation(projects.libraries.uiStrings)
// Cardano - using Koios backend (no API key required)
implementation("com.bloxbean.cardano:cardano-client-lib:0.7.1")
implementation("com.bloxbean.cardano:cardano-client-backend-koios:0.7.1")
implementation("com.bloxbean.cardano:cardano-client-crypto:0.7.1")
// Biometric
implementation(libs.androidx.biometric)
// JSON
implementation(libs.serialization.json)
// Coroutines
implementation(libs.coroutines.core)
testImplementation(projects.features.wallet.test)
testImplementation(libs.test.junit)
testImplementation(libs.test.truth)
testImplementation(libs.coroutines.test)
}
New: features/wallet/test/build.gradle.kts
plugins {
id("io.element.android-library")
}
android {
namespace = "io.element.android.features.wallet.test"
}
dependencies {
api(projects.features.wallet.api)
implementation(libs.coroutines.core)
}
New: features/wallet/api/src/main/kotlin/io/element/android/features/wallet/api/WalletEntryPoint.kt
package io.element.android.features.wallet.api
import com.bumble.appyx.core.modality.BuildContext
import com.bumble.appyx.core.node.Node
interface WalletEntryPoint {
fun nodeBuilder(parentNode: Node, buildContext: BuildContext): NodeBuilder
interface NodeBuilder {
fun params(params: Params): NodeBuilder
fun build(): Node
}
data class Params(
val roomId: String,
val recipientUserId: String?,
val recipientAddress: String?,
val amount: String?,
)
}
New: features/wallet/api/src/main/kotlin/io/element/android/features/wallet/api/WalletState.kt
package io.element.android.features.wallet.api
data class WalletState(
val hasWallet: Boolean,
val address: String?,
val balanceLovelace: Long?,
val balanceAda: String?,
val isLoading: Boolean,
val error: String?,
)
New: features/wallet/impl/src/main/kotlin/io/element/android/features/wallet/impl/di/WalletModule.kt
package io.element.android.features.wallet.impl.di
import com.squareup.anvil.annotations.ContributesTo
import dagger.Binds
import dagger.Module
import dagger.Provides
import io.element.android.features.wallet.api.WalletEntryPoint
import io.element.android.features.wallet.impl.DefaultWalletEntryPoint
import io.element.android.features.wallet.impl.cardano.CardanoClient
import io.element.android.features.wallet.impl.cardano.KoiosCardanoClient
import io.element.android.features.wallet.impl.storage.CardanoKeyStorage
import io.element.android.features.wallet.impl.storage.CardanoKeyStorageImpl
import io.element.android.libraries.di.AppScope
import io.element.android.libraries.di.SingleIn
@Module
@ContributesTo(AppScope::class)
interface WalletModule {
@Binds
fun bindWalletEntryPoint(impl: DefaultWalletEntryPoint): WalletEntryPoint
@Binds
fun bindCardanoKeyStorage(impl: CardanoKeyStorageImpl): CardanoKeyStorage
@Binds
fun bindCardanoClient(impl: KoiosCardanoClient): CardanoClient
}
Modify: settings.gradle.kts (root)
Add to features section:
include(":features:wallet:api")
include(":features:wallet:impl")
include(":features:wallet:test")
Modify: app/build.gradle.kts
Add dependency:
implementation(projects.features.wallet.impl)
Key Implementation Details
- Module structure follows Element X pattern:
api/impl/testseparation - Anvil for DI: Use
@ContributesBindingand@ContributesToannotations - AppScope: Wallet services are app-scoped (singleton per app lifecycle)
- SessionScope consideration: If wallet-per-account is needed later, migrate to SessionScope
- No API key needed: Koios public API at
api.koios.restrequires no registration
Gotchas
- ProGuard rules:
cardano-client-libuses reflection for CBOR. Add toproguard-rules.pro:-keep class com.bloxbean.cardano.** { *; } -keepclassmembers class * { @com.fasterxml.jackson.annotation.* *; } - Multidex: The Cardano library is large. Ensure multidex is enabled (it should be already).
- minSdk: cardano-client-lib requires API 21+. Element X is API 23+, so we're fine.
Task 2: Key Generation + Storage (CardanoKeyStorage)
Blocks: Task 4 (Transaction Builder)
Blocked by: Task 1
Effort: 3 days
Acceptance criteria:
- New wallet generates valid 24-word BIP-39 mnemonic
- Mnemonic encrypts with Android Keystore key
- Mnemonic decrypts correctly after biometric auth
- Derived addresses match cardano-client-lib reference
- Seed phrase backup screen shows words with FLAG_SECURE
- Wallet deletion clears all key material
- Unit tests pass for key derivation paths
Files
New: features/wallet/impl/src/main/kotlin/io/element/android/features/wallet/impl/storage/CardanoKeyStorage.kt
package io.element.android.features.wallet.impl.storage
import io.element.android.libraries.matrix.api.core.SessionId
interface CardanoKeyStorage {
suspend fun hasWallet(sessionId: SessionId): Boolean
suspend fun createWallet(sessionId: SessionId): Result<WalletCreationResult>
suspend fun importWallet(sessionId: SessionId, mnemonic: String): Result<Unit>
suspend fun getMnemonic(sessionId: SessionId): Result<String>
suspend fun getSpendingKey(sessionId: SessionId, addressIndex: Int = 0): Result<ByteArray>
suspend fun getBaseAddress(sessionId: SessionId, addressIndex: Int = 0): Result<String>
suspend fun getStakeAddress(sessionId: SessionId): Result<String>
suspend fun deleteWallet(sessionId: SessionId): Result<Unit>
}
data class WalletCreationResult(
val mnemonic: String,
val baseAddress: String,
val stakeAddress: String,
)
New: features/wallet/impl/src/main/kotlin/io/element/android/features/wallet/impl/storage/CardanoKeyStorageImpl.kt
package io.element.android.features.wallet.impl.storage
import android.content.Context
import androidx.security.crypto.EncryptedSharedPreferences
import androidx.security.crypto.MasterKey
import com.bloxbean.cardano.client.account.Account
import com.bloxbean.cardano.client.common.model.Networks
import com.bloxbean.cardano.client.crypto.bip39.MnemonicCode
import com.squareup.anvil.annotations.ContributesBinding
import io.element.android.libraries.cryptography.api.SecretKeyRepository
import io.element.android.libraries.di.AppScope
import io.element.android.libraries.di.ApplicationContext
import io.element.android.libraries.matrix.api.core.SessionId
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import java.security.SecureRandom
import javax.crypto.Cipher
import javax.crypto.spec.GCMParameterSpec
import javax.inject.Inject
@ContributesBinding(AppScope::class)
class CardanoKeyStorageImpl @Inject constructor(
@ApplicationContext private val context: Context,
private val secretKeyRepository: SecretKeyRepository,
) : CardanoKeyStorage {
companion object {
private const val PREFS_NAME = "cardano_wallet_prefs"
private const val KEY_ENCRYPTED_MNEMONIC = "encrypted_mnemonic_"
private const val KEY_IV = "iv_"
private const val KEYSTORE_ALIAS_PREFIX = "cardano_wallet_"
private const val GCM_TAG_LENGTH = 128
private const val GCM_IV_LENGTH = 12
}
private val masterKey by lazy {
MasterKey.Builder(context)
.setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
.setUserAuthenticationRequired(true)
.setUserAuthenticationParameters(
30, // validity duration in seconds
MasterKey.AUTH_BIOMETRIC_STRONG or MasterKey.AUTH_DEVICE_CREDENTIAL
)
.build()
}
private fun getPrefs() = EncryptedSharedPreferences.create(
context,
PREFS_NAME,
masterKey,
EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
)
override suspend fun hasWallet(sessionId: SessionId): Boolean = withContext(Dispatchers.IO) {
val prefs = getPrefs()
prefs.contains(KEY_ENCRYPTED_MNEMONIC + sessionId.value)
}
override suspend fun createWallet(sessionId: SessionId): Result<WalletCreationResult> =
withContext(Dispatchers.IO) {
runCatching {
// Generate 24-word mnemonic (256 bits entropy)
val mnemonicCode = MnemonicCode()
val entropy = ByteArray(32).also { SecureRandom().nextBytes(it) }
val mnemonic = mnemonicCode.toMnemonic(entropy).joinToString(" ")
// Store encrypted
storeMnemonic(sessionId, mnemonic)
// Derive addresses
val account = Account(Networks.mainnet(), mnemonic)
WalletCreationResult(
mnemonic = mnemonic,
baseAddress = account.baseAddress(),
stakeAddress = account.stakeAddress(),
)
}
}
override suspend fun importWallet(sessionId: SessionId, mnemonic: String): Result<Unit> =
withContext(Dispatchers.IO) {
runCatching {
// Validate mnemonic
val words = mnemonic.trim().split("\\s+".toRegex())
require(words.size in listOf(12, 15, 18, 21, 24)) {
"Invalid mnemonic length: ${words.size} words"
}
// Verify it's valid BIP-39
val mnemonicCode = MnemonicCode()
mnemonicCode.check(words)
// Verify it derives valid Cardano addresses
Account(Networks.mainnet(), mnemonic)
// Store encrypted
storeMnemonic(sessionId, mnemonic)
}
}
override suspend fun getMnemonic(sessionId: SessionId): Result<String> =
withContext(Dispatchers.IO) {
runCatching {
retrieveMnemonic(sessionId)
}
}
override suspend fun getSpendingKey(sessionId: SessionId, addressIndex: Int): Result<ByteArray> =
withContext(Dispatchers.IO) {
runCatching {
val mnemonic = retrieveMnemonic(sessionId)
val account = Account(Networks.mainnet(), mnemonic, addressIndex)
account.privateKeyBytes()
}
}
override suspend fun getBaseAddress(sessionId: SessionId, addressIndex: Int): Result<String> =
withContext(Dispatchers.IO) {
runCatching {
val mnemonic = retrieveMnemonic(sessionId)
val account = Account(Networks.mainnet(), mnemonic, addressIndex)
account.baseAddress()
}
}
override suspend fun getStakeAddress(sessionId: SessionId): Result<String> =
withContext(Dispatchers.IO) {
runCatching {
val mnemonic = retrieveMnemonic(sessionId)
val account = Account(Networks.mainnet(), mnemonic)
account.stakeAddress()
}
}
override suspend fun deleteWallet(sessionId: SessionId): Result<Unit> =
withContext(Dispatchers.IO) {
runCatching {
val prefs = getPrefs()
prefs.edit()
.remove(KEY_ENCRYPTED_MNEMONIC + sessionId.value)
.remove(KEY_IV + sessionId.value)
.apply()
// Delete keystore key
secretKeyRepository.deleteKey(KEYSTORE_ALIAS_PREFIX + sessionId.value)
}
}
private fun storeMnemonic(sessionId: SessionId, mnemonic: String) {
val keyAlias = KEYSTORE_ALIAS_PREFIX + sessionId.value
val secretKey = secretKeyRepository.getOrCreateKey(
alias = keyAlias,
requiresUserAuthentication = true
)
val cipher = Cipher.getInstance("AES/GCM/NoPadding")
cipher.init(Cipher.ENCRYPT_MODE, secretKey)
val iv = cipher.iv
val encrypted = cipher.doFinal(mnemonic.toByteArray(Charsets.UTF_8))
val prefs = getPrefs()
prefs.edit()
.putString(KEY_ENCRYPTED_MNEMONIC + sessionId.value,
android.util.Base64.encodeToString(encrypted, android.util.Base64.NO_WRAP))
.putString(KEY_IV + sessionId.value,
android.util.Base64.encodeToString(iv, android.util.Base64.NO_WRAP))
.apply()
}
private fun retrieveMnemonic(sessionId: SessionId): String {
val prefs = getPrefs()
val encryptedB64 = prefs.getString(KEY_ENCRYPTED_MNEMONIC + sessionId.value, null)
?: throw IllegalStateException("No wallet found for session")
val ivB64 = prefs.getString(KEY_IV + sessionId.value, null)
?: throw IllegalStateException("No IV found for session")
val encrypted = android.util.Base64.decode(encryptedB64, android.util.Base64.NO_WRAP)
val iv = android.util.Base64.decode(ivB64, android.util.Base64.NO_WRAP)
val keyAlias = KEYSTORE_ALIAS_PREFIX + sessionId.value
val secretKey = secretKeyRepository.getOrCreateKey(
alias = keyAlias,
requiresUserAuthentication = true
)
val cipher = Cipher.getInstance("AES/GCM/NoPadding")
val spec = GCMParameterSpec(GCM_TAG_LENGTH, iv)
cipher.init(Cipher.DECRYPT_MODE, secretKey, spec)
return String(cipher.doFinal(encrypted), Charsets.UTF_8)
}
}
New: features/wallet/impl/src/main/kotlin/io/element/android/features/wallet/impl/setup/SeedPhraseBackupScreen.kt
package io.element.android.features.wallet.impl.setup
import android.view.WindowManager
import androidx.compose.foundation.layout.*
import androidx.compose.foundation.lazy.grid.GridCells
import androidx.compose.foundation.lazy.grid.LazyVerticalGrid
import androidx.compose.foundation.lazy.grid.itemsIndexed
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalView
import androidx.compose.ui.unit.dp
import io.element.android.libraries.designsystem.theme.components.Button
import io.element.android.libraries.designsystem.theme.components.Text
@Composable
fun SeedPhraseBackupScreen(
words: List<String>,
onConfirm: () -> Unit,
onBack: () -> Unit,
modifier: Modifier = Modifier,
) {
// FLAG_SECURE to prevent screenshots
val view = LocalView.current
DisposableEffect(Unit) {
val window = (view.context as? android.app.Activity)?.window
window?.addFlags(WindowManager.LayoutParams.FLAG_SECURE)
onDispose {
window?.clearFlags(WindowManager.LayoutParams.FLAG_SECURE)
}
}
Column(
modifier = modifier
.fillMaxSize()
.padding(16.dp),
horizontalAlignment = Alignment.CenterHorizontally,
) {
Text(
text = "Your Recovery Phrase",
style = MaterialTheme.typography.headlineMedium,
)
Spacer(modifier = Modifier.height(8.dp))
Text(
text = "Write down these 24 words in order. Never share them with anyone.",
style = MaterialTheme.typography.bodyMedium,
color = MaterialTheme.colorScheme.error,
)
Spacer(modifier = Modifier.height(24.dp))
LazyVerticalGrid(
columns = GridCells.Fixed(3),
verticalArrangement = Arrangement.spacedBy(8.dp),
horizontalArrangement = Arrangement.spacedBy(8.dp),
modifier = Modifier.weight(1f),
) {
itemsIndexed(words) { index, word ->
SeedWordItem(index = index + 1, word = word)
}
}
Spacer(modifier = Modifier.height(24.dp))
Button(
text = "I've written it down",
onClick = onConfirm,
modifier = Modifier.fillMaxWidth(),
)
Spacer(modifier = Modifier.height(8.dp))
TextButton(onClick = onBack) {
Text("Go back")
}
}
}
@Composable
private fun SeedWordItem(
index: Int,
word: String,
modifier: Modifier = Modifier,
) {
Surface(
modifier = modifier,
shape = MaterialTheme.shapes.small,
color = MaterialTheme.colorScheme.surfaceVariant,
) {
Row(
modifier = Modifier.padding(8.dp),
verticalAlignment = Alignment.CenterVertically,
) {
Text(
text = "$index.",
style = MaterialTheme.typography.labelSmall,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
Spacer(modifier = Modifier.width(4.dp))
Text(
text = word,
style = MaterialTheme.typography.bodyMedium,
)
}
}
}
New: features/wallet/impl/src/main/kotlin/io/element/android/features/wallet/impl/biometric/BiometricAuthenticator.kt
package io.element.android.features.wallet.impl.biometric
import android.content.Context
import androidx.biometric.BiometricManager
import androidx.biometric.BiometricPrompt
import androidx.core.content.ContextCompat
import androidx.fragment.app.FragmentActivity
import kotlinx.coroutines.suspendCancellableCoroutine
import javax.inject.Inject
import kotlin.coroutines.resume
class BiometricAuthenticator @Inject constructor() {
sealed class AuthResult {
object Success : AuthResult()
data class Error(val code: Int, val message: String) : AuthResult()
object Cancelled : AuthResult()
}
fun canAuthenticate(context: Context): Boolean {
val biometricManager = BiometricManager.from(context)
return biometricManager.canAuthenticate(
BiometricManager.Authenticators.BIOMETRIC_STRONG or
BiometricManager.Authenticators.DEVICE_CREDENTIAL
) == BiometricManager.BIOMETRIC_SUCCESS
}
suspend fun authenticate(
activity: FragmentActivity,
title: String = "Authenticate",
subtitle: String = "Confirm your identity to continue",
negativeButtonText: String = "Cancel",
): AuthResult = suspendCancellableCoroutine { continuation ->
val executor = ContextCompat.getMainExecutor(activity)
val callback = object : BiometricPrompt.AuthenticationCallback() {
override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
if (continuation.isActive) {
continuation.resume(AuthResult.Success)
}
}
override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
if (continuation.isActive) {
if (errorCode == BiometricPrompt.ERROR_USER_CANCELED ||
errorCode == BiometricPrompt.ERROR_NEGATIVE_BUTTON ||
errorCode == BiometricPrompt.ERROR_CANCELED) {
continuation.resume(AuthResult.Cancelled)
} else {
continuation.resume(AuthResult.Error(errorCode, errString.toString()))
}
}
}
override fun onAuthenticationFailed() {
// Don't resume yet - user can retry
}
}
val biometricPrompt = BiometricPrompt(activity, executor, callback)
val promptInfo = BiometricPrompt.PromptInfo.Builder()
.setTitle(title)
.setSubtitle(subtitle)
.setAllowedAuthenticators(
BiometricManager.Authenticators.BIOMETRIC_STRONG or
BiometricManager.Authenticators.DEVICE_CREDENTIAL
)
.build()
biometricPrompt.authenticate(promptInfo)
continuation.invokeOnCancellation {
biometricPrompt.cancelAuthentication()
}
}
}
Key Implementation Details
- BIP-39 Mnemonic: Use
MnemonicCodefrom cardano-client-lib for generation and validation - CIP-1852 Derivation:
Accountclass handles this internally:- Path:
m/1852'/1815'/0'/0/0for first external address - Path:
m/1852'/1815'/0'/2/0for staking key
- Path:
- Storage layers:
- Mnemonic → AES-GCM encrypted → EncryptedSharedPreferences
- AES key → Android Keystore with biometric gate
- Per-session wallets: Each Matrix session can have its own wallet (keyed by
sessionId) - Keys derived on demand: Only mnemonic is stored; spending keys derived when needed
Gotchas
- Biometric fallback: Some devices only have PIN. Use
AUTH_DEVICE_CREDENTIALas fallback. - Keystore invalidation: If user changes biometrics, keys may be invalidated. Handle
KeyPermanentlyInvalidatedException. - Memory zeroization: Clear mnemonic bytes after use (
Arrays.fill(bytes, 0.toByte())). - Thread safety: Keystore operations are blocking; always use
Dispatchers.IO. - cardano-client-lib entropy: Generate entropy yourself with
SecureRandom, don't rely on library defaults.
Task 3: Koios Client
Blocks: Task 4 (Transaction Builder)
Blocked by: Task 1
Effort: 1 day
Acceptance criteria:
- Fetch UTXOs for an address returns correct data
- Fetch balance matches sum of UTXO values
- Submit transaction returns tx hash
- Query tx status returns confirmation count
- Network errors surface as typed errors, not crashes
Files
New: features/wallet/impl/src/main/kotlin/io/element/android/features/wallet/impl/cardano/CardanoClient.kt
package io.element.android.features.wallet.impl.cardano
import com.bloxbean.cardano.client.api.model.Utxo
interface CardanoClient {
suspend fun getUtxos(address: String): Result<List<Utxo>>
suspend fun getBalance(address: String): Result<Long> // lovelace
suspend fun submitTransaction(txCbor: ByteArray): Result<String> // tx hash
suspend fun getTransactionStatus(txHash: String): Result<TransactionStatus>
suspend fun getProtocolParameters(): Result<ProtocolParameters>
}
data class TransactionStatus(
val txHash: String,
val confirmed: Boolean,
val confirmations: Int,
val slot: Long?,
val blockHeight: Long?,
)
data class ProtocolParameters(
val minFeeA: Long, // lovelace per byte
val minFeeB: Long, // base fee
val maxTxSize: Int,
val coinsPerUtxoWord: Long,
val poolDeposit: Long,
val keyDeposit: Long,
)
New: features/wallet/impl/src/main/kotlin/io/element/android/features/wallet/impl/cardano/KoiosCardanoClient.kt
package io.element.android.features.wallet.impl.cardano
import com.bloxbean.cardano.client.api.model.Utxo
import com.bloxbean.cardano.client.backend.factory.BackendFactory
import com.bloxbean.cardano.client.common.model.Networks
import com.bloxbean.cardano.client.util.Constants
import com.squareup.anvil.annotations.ContributesBinding
import io.element.android.libraries.di.AppScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.delay
import kotlinx.coroutines.withContext
import javax.inject.Inject
/**
* Cardano chain client using Koios public API.
*
* Koios is a decentralized API layer for Cardano with no API key required.
* Rate limits: 100 req/10s for anonymous users.
*
* @see <a href="https://api.koios.rest/">Koios API Documentation</a>
*/
@ContributesBinding(AppScope::class)
class KoiosCardanoClient @Inject constructor() : CardanoClient {
companion object {
private const val MAX_RETRIES = 3
private const val INITIAL_BACKOFF_MS = 1000L
}
// Koios backend - no API key needed
private val backendService by lazy {
BackendFactory.getKoiosBackendService(Constants.KOIOS_MAINNET_URL)
}
override suspend fun getUtxos(address: String): Result<List<Utxo>> =
withRetry {
withContext(Dispatchers.IO) {
val result = backendService.utxoService.getUtxos(address, 100, 1)
if (result.isSuccessful) {
Result.success(result.value)
} else {
Result.failure(CardanoClientException(result.response))
}
}
}
override suspend fun getBalance(address: String): Result<Long> =
withRetry {
withContext(Dispatchers.IO) {
val result = backendService.addressService.getAddressInfo(address)
if (result.isSuccessful) {
val info = result.value
val lovelace = info.amount
.find { it.unit == "lovelace" }
?.quantity?.toLongOrNull() ?: 0L
Result.success(lovelace)
} else {
Result.failure(CardanoClientException(result.response))
}
}
}
override suspend fun submitTransaction(txCbor: ByteArray): Result<String> =
withRetry {
withContext(Dispatchers.IO) {
val result = backendService.transactionService.submitTransaction(txCbor)
if (result.isSuccessful) {
Result.success(result.value)
} else {
Result.failure(CardanoClientException(result.response))
}
}
}
override suspend fun getTransactionStatus(txHash: String): Result<TransactionStatus> =
withRetry {
withContext(Dispatchers.IO) {
val result = backendService.transactionService.getTransaction(txHash)
if (result.isSuccessful) {
val tx = result.value
Result.success(TransactionStatus(
txHash = txHash,
confirmed = true,
confirmations = 1,
slot = tx.slot,
blockHeight = tx.blockHeight,
))
} else if (result.response?.contains("404") == true) {
// Not yet confirmed
Result.success(TransactionStatus(
txHash = txHash,
confirmed = false,
confirmations = 0,
slot = null,
blockHeight = null,
))
} else {
Result.failure(CardanoClientException(result.response))
}
}
}
override suspend fun getProtocolParameters(): Result<ProtocolParameters> =
withRetry {
withContext(Dispatchers.IO) {
val result = backendService.epochService.protocolParameters
if (result.isSuccessful) {
val params = result.value
Result.success(ProtocolParameters(
minFeeA = params.minFeeA.toLong(),
minFeeB = params.minFeeB.toLong(),
maxTxSize = params.maxTxSize,
coinsPerUtxoWord = params.coinsPerUtxoSize?.toLong() ?: 4310L,
poolDeposit = params.poolDeposit.toLong(),
keyDeposit = params.keyDeposit.toLong(),
))
} else {
Result.failure(CardanoClientException(result.response))
}
}
}
private suspend fun <T> withRetry(block: suspend () -> Result<T>): Result<T> {
var lastException: Throwable? = null
var backoff = INITIAL_BACKOFF_MS
repeat(MAX_RETRIES) { attempt ->
val result = block()
if (result.isSuccess) {
return result
}
val exception = result.exceptionOrNull()
lastException = exception
// Check if retryable
if (exception is CardanoClientException) {
if (exception.isRateLimited() || exception.isRetryable()) {
delay(backoff)
backoff *= 2
} else {
return result
}
} else {
return result
}
}
return Result.failure(lastException ?: Exception("Max retries exceeded"))
}
}
class CardanoClientException(val response: String?) : Exception(response) {
fun isRateLimited(): Boolean = response?.contains("429") == true
fun isRetryable(): Boolean = response?.let {
it.contains("429") || it.contains("500") || it.contains("503")
} ?: false
}
Key Implementation Details
- Koios backend: Use
BackendFactory.getKoiosBackendService(Constants.KOIOS_MAINNET_URL)from cardano-client-lib - No API key: Koios public API at
api.koios.restrequires no registration - Same interface: Koios backend implements the same
BackendServiceinterface as Blockfrost - Retry strategy: Exponential backoff for 429 (rate limit) and 5xx errors
- Thread context: All network calls on
Dispatchers.IO
Gotchas
- Rate limits: Koios public tier is 100 req/10s. Implement backoff for rate limit responses.
- Mainnet vs testnet: Use
Constants.KOIOS_TESTNET_URLfor testing. - UTXO pagination: Koios paginates at 100. For large wallets, implement pagination.
- Decentralized: Koios has multiple providers; some may have slightly different sync status.
Task 4: Transaction Builder
Blocks: Task 6 (Payment Flow UI)
Blocked by: Tasks 2, 3
Effort: 3 days
Acceptance criteria:
- Build valid tx spending from single UTXO
- Build valid tx spending from multiple UTXOs (coin selection)
- Fee calculation matches on-chain acceptance
- Change output correctly calculated
- Transaction signed and serialized to valid CBOR
- Insufficient funds error surfaces clearly
- No UTXO error handled
- Min UTXO value enforced (no dust outputs)
Files
New: features/wallet/impl/src/main/kotlin/io/element/android/features/wallet/impl/cardano/TransactionBuilder.kt
package io.element.android.features.wallet.impl.cardano
interface TransactionBuilder {
suspend fun buildPayment(
senderAddress: String,
recipientAddress: String,
amountLovelace: Long,
mnemonic: String,
): Result<BuiltTransaction>
suspend fun estimateFee(
senderAddress: String,
recipientAddress: String,
amountLovelace: Long,
): Result<Long>
}
data class BuiltTransaction(
val txCbor: ByteArray,
val txHash: String,
val fee: Long,
val inputsLovelace: Long,
val outputsLovelace: Long,
val changeLovelace: Long,
)
sealed class TransactionBuildError : Exception() {
object InsufficientFunds : TransactionBuildError()
object NoUtxosAvailable : TransactionBuildError()
data class InvalidAddress(val address: String) : TransactionBuildError()
data class AmountTooSmall(val minAmount: Long) : TransactionBuildError()
data class BuildFailed(override val message: String) : TransactionBuildError()
}
New: features/wallet/impl/src/main/kotlin/io/element/android/features/wallet/impl/cardano/TransactionBuilderImpl.kt
package io.element.android.features.wallet.impl.cardano
import com.bloxbean.cardano.client.account.Account
import com.bloxbean.cardano.client.address.AddressProvider
import com.bloxbean.cardano.client.api.model.Amount
import com.bloxbean.cardano.client.backend.factory.BackendFactory
import com.bloxbean.cardano.client.coinselection.impl.LargestFirstUtxoSelectionStrategy
import com.bloxbean.cardano.client.common.model.Networks
import com.bloxbean.cardano.client.function.helper.SignerProviders
import com.bloxbean.cardano.client.quicktx.QuickTxBuilder
import com.bloxbean.cardano.client.quicktx.Tx
import com.bloxbean.cardano.client.util.Constants
import com.squareup.anvil.annotations.ContributesBinding
import io.element.android.libraries.di.AppScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import javax.inject.Inject
@ContributesBinding(AppScope::class)
class TransactionBuilderImpl @Inject constructor(
private val cardanoClient: CardanoClient,
) : TransactionBuilder {
companion object {
private const val MIN_UTXO_LOVELACE = 1_000_000L // 1 ADA minimum for outputs
}
private val backendService by lazy {
BackendFactory.getKoiosBackendService(Constants.KOIOS_MAINNET_URL)
}
override suspend fun buildPayment(
senderAddress: String,
recipientAddress: String,
amountLovelace: Long,
mnemonic: String,
): Result<BuiltTransaction> = withContext(Dispatchers.IO) {
runCatching {
// Validate addresses
validateAddress(senderAddress)
validateAddress(recipientAddress)
// Validate amount
if (amountLovelace < MIN_UTXO_LOVELACE) {
throw TransactionBuildError.AmountTooSmall(MIN_UTXO_LOVELACE)
}
// Check UTXOs exist
val utxosResult = cardanoClient.getUtxos(senderAddress)
val utxos = utxosResult.getOrThrow()
if (utxos.isEmpty()) {
throw TransactionBuildError.NoUtxosAvailable
}
// Calculate total available
val totalAvailable = utxos.sumOf { utxo ->
utxo.amount.find { it.unit == "lovelace" }?.quantity?.toLongOrNull() ?: 0L
}
// Quick check for insufficient funds (rough estimate)
if (totalAvailable < amountLovelace + 200_000) { // rough fee estimate
throw TransactionBuildError.InsufficientFunds
}
// Create account from mnemonic
val account = Account(Networks.mainnet(), mnemonic)
// Build transaction using QuickTx API
val tx = Tx()
.payToAddress(recipientAddress, Amount.lovelace(amountLovelace))
.from(senderAddress)
val quickTxBuilder = QuickTxBuilder(backendService)
// Build and sign
val result = quickTxBuilder
.compose(tx)
.withSigner(SignerProviders.signerFrom(account))
.withUtxoSelectionStrategy(LargestFirstUtxoSelectionStrategy(backendService.utxoService))
.complete()
if (!result.isSuccessful) {
// Check if it's insufficient funds
if (result.response?.contains("insufficient", ignoreCase = true) == true ||
result.response?.contains("not enough", ignoreCase = true) == true) {
throw TransactionBuildError.InsufficientFunds
}
throw TransactionBuildError.BuildFailed(result.response ?: "Unknown error")
}
val signedTx = result.value
val txBytes = signedTx.serialize()
val txHash = signedTx.transactionId
// Calculate fee from tx body
val fee = signedTx.body.fee.toLong()
// Calculate totals
val inputsTotal = signedTx.body.inputs.sumOf { input ->
utxos.find { it.txHash == input.transactionId && it.outputIndex == input.index }
?.amount?.find { it.unit == "lovelace" }?.quantity?.toLongOrNull() ?: 0L
}
val outputsTotal = signedTx.body.outputs.sumOf { output ->
output.value.coin.toLong()
}
val changeAmount = outputsTotal - amountLovelace
BuiltTransaction(
txCbor = txBytes,
txHash = txHash,
fee = fee,
inputsLovelace = inputsTotal,
outputsLovelace = outputsTotal,
changeLovelace = changeAmount,
)
}
}
override suspend fun estimateFee(
senderAddress: String,
recipientAddress: String,
amountLovelace: Long,
): Result<Long> = withContext(Dispatchers.IO) {
runCatching {
// Get protocol parameters
val params = cardanoClient.getProtocolParameters().getOrThrow()
// Estimate tx size (typical simple payment is ~250-350 bytes)
val estimatedSize = 350
// fee = a * size + b
val fee = params.minFeeA * estimatedSize + params.minFeeB
fee
}
}
private fun validateAddress(address: String) {
if (!address.startsWith("addr1") && !address.startsWith("addr_test1")) {
throw TransactionBuildError.InvalidAddress(address)
}
try {
AddressProvider.getAddress(address)
} catch (e: Exception) {
throw TransactionBuildError.InvalidAddress(address)
}
}
}
New: features/wallet/impl/src/main/kotlin/io/element/android/features/wallet/impl/cardano/CardanoWalletManager.kt
package io.element.android.features.wallet.impl.cardano
import io.element.android.features.wallet.api.WalletState
import io.element.android.features.wallet.impl.storage.CardanoKeyStorage
import io.element.android.libraries.matrix.api.core.SessionId
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import javax.inject.Inject
class CardanoWalletManager @Inject constructor(
private val keyStorage: CardanoKeyStorage,
private val cardanoClient: CardanoClient,
private val transactionBuilder: TransactionBuilder,
) {
private val _walletState = MutableStateFlow(WalletState(
hasWallet = false,
address = null,
balanceLovelace = null,
balanceAda = null,
isLoading = true,
error = null,
))
val walletState: StateFlow<WalletState> = _walletState.asStateFlow()
suspend fun initialize(sessionId: SessionId) {
_walletState.value = _walletState.value.copy(isLoading = true, error = null)
val hasWallet = keyStorage.hasWallet(sessionId)
if (hasWallet) {
val address = keyStorage.getBaseAddress(sessionId).getOrNull()
_walletState.value = _walletState.value.copy(
hasWallet = true,
address = address,
isLoading = false,
)
// Fetch balance in background
address?.let { refreshBalance(it) }
} else {
_walletState.value = _walletState.value.copy(
hasWallet = false,
address = null,
isLoading = false,
)
}
}
suspend fun refreshBalance(address: String) {
val result = cardanoClient.getBalance(address)
result.onSuccess { lovelace ->
_walletState.value = _walletState.value.copy(
balanceLovelace = lovelace,
balanceAda = formatAda(lovelace),
error = null,
)
}.onFailure { error ->
_walletState.value = _walletState.value.copy(
error = error.message,
)
}
}
suspend fun sendPayment(
sessionId: SessionId,
recipientAddress: String,
amountLovelace: Long,
): Result<String> {
val mnemonic = keyStorage.getMnemonic(sessionId).getOrElse {
return Result.failure(it)
}
val senderAddress = keyStorage.getBaseAddress(sessionId).getOrElse {
return Result.failure(it)
}
// Build transaction
val builtTx = transactionBuilder.buildPayment(
senderAddress = senderAddress,
recipientAddress = recipientAddress,
amountLovelace = amountLovelace,
mnemonic = mnemonic,
).getOrElse {
return Result.failure(it)
}
// Submit transaction
val txHash = cardanoClient.submitTransaction(builtTx.txCbor).getOrElse {
return Result.failure(it)
}
// Refresh balance
refreshBalance(senderAddress)
return Result.success(txHash)
}
private fun formatAda(lovelace: Long): String {
val ada = lovelace / 1_000_000.0
return "%.6f".format(ada).trimEnd('0').trimEnd('.')
}
}
Key Implementation Details
- Coin selection: Use
LargestFirstUtxoSelectionStrategyfrom cardano-client-lib- Selects largest UTXOs first to minimize inputs
- Handles multi-UTXO scenarios automatically
- QuickTx API: High-level builder handles fee calculation, change output, serialization
- Signing:
SignerProviders.signerFrom(account)signs with derived spending key - Fee calculation: Automatic based on protocol parameters and tx size
- Change output: Library adds change output automatically to sender address
Gotchas
- Min UTXO value: Outputs must be ≥1 ADA to avoid "UTxO too small" error
- Insufficient funds edge case: When amount + fee ≈ total balance, may fail to build change output
- UTXO exhaustion: After many small txs, may have many dust UTXOs. Consider UTXO consolidation later.
- TTL (time-to-live): Transactions expire after ~2 hours by default. User should be warned if tx isn't submitted quickly.
- Memory security: Zero out mnemonic array after building tx:
val mnemonicBytes = mnemonic.toByteArray() try { ... } finally { mnemonicBytes.fill(0) }
Task 5: /pay Slash Command Parser + SuggestionsProcessor Extension
Blocks: Task 6 (Payment Flow UI)
Blocked by: Task 1
Effort: 2 days
Acceptance criteria:
- Typing
/shows "pay" as suggestion /paysuggestion shows helpful description- Selecting
/payauto-completes to/pay /pay 10 ADA @jacobparses correctly/pay 10 ADA addr1q...parses correctly- Invalid syntax surfaces clear error
- Pressing send with
/pay ...intercepts and opens payment flow - User can cancel and return to composer
Files
New: features/wallet/api/src/main/kotlin/io/element/android/features/wallet/api/slash/SlashCommand.kt
package io.element.android.features.wallet.api.slash
import io.element.android.libraries.matrix.api.core.UserId
sealed interface SlashCommand {
data class Pay(
val amount: Double,
val unit: PaymentUnit,
val recipient: PaymentRecipient,
) : SlashCommand
}
enum class PaymentUnit(val symbol: String, val lovelaceMultiplier: Long) {
ADA("ADA", 1_000_000L),
LOVELACE("lovelace", 1L),
}
sealed interface PaymentRecipient {
data class MatrixUser(val userId: UserId) : PaymentRecipient
data class CardanoAddress(val address: String) : PaymentRecipient
}
New: features/wallet/impl/src/main/kotlin/io/element/android/features/wallet/impl/slash/SlashCommandParser.kt
package io.element.android.features.wallet.impl.slash
import io.element.android.features.wallet.api.slash.PaymentRecipient
import io.element.android.features.wallet.api.slash.PaymentUnit
import io.element.android.features.wallet.api.slash.SlashCommand
import io.element.android.libraries.matrix.api.core.UserId
import javax.inject.Inject
class SlashCommandParser @Inject constructor() {
companion object {
// /pay <amount> <unit> <recipient>
// e.g., /pay 10 ADA @user:matrix.org
// e.g., /pay 5.5 ADA addr1q...
private val PAY_REGEX = Regex(
"""^/pay\s+(\d+(?:\.\d+)?)\s+(\w+)\s+(.+)$""",
RegexOption.IGNORE_CASE
)
// Cardano mainnet address prefix
private val CARDANO_ADDRESS_REGEX = Regex("""^addr1[a-z0-9]+$""", RegexOption.IGNORE_CASE)
}
sealed class ParseResult {
data class Success(val command: SlashCommand) : ParseResult()
data class Error(val message: String) : ParseResult()
object NotACommand : ParseResult()
}
fun parse(input: String): ParseResult {
val trimmed = input.trim()
if (!trimmed.startsWith("/")) {
return ParseResult.NotACommand
}
if (!trimmed.startsWith("/pay", ignoreCase = true)) {
return ParseResult.NotACommand
}
val match = PAY_REGEX.matchEntire(trimmed)
?: return ParseResult.Error("Invalid format. Use: /pay <amount> <unit> <@user or addr1...>")
val (amountStr, unitStr, recipientStr) = match.destructured
// Parse amount
val amount = amountStr.toDoubleOrNull()
?: return ParseResult.Error("Invalid amount: $amountStr")
if (amount <= 0) {
return ParseResult.Error("Amount must be positive")
}
// Parse unit
val unit = when (unitStr.uppercase()) {
"ADA" -> PaymentUnit.ADA
"LOVELACE" -> PaymentUnit.LOVELACE
else -> return ParseResult.Error("Invalid unit: $unitStr. Use ADA or lovelace")
}
// Parse recipient
val recipient = parseRecipient(recipientStr.trim())
?: return ParseResult.Error("Invalid recipient. Use @user:server or addr1...")
return ParseResult.Success(SlashCommand.Pay(
amount = amount,
unit = unit,
recipient = recipient,
))
}
private fun parseRecipient(input: String): PaymentRecipient? {
return when {
// Matrix user ID
input.startsWith("@") -> {
try {
PaymentRecipient.MatrixUser(UserId(input))
} catch (e: Exception) {
null
}
}
// Cardano address
CARDANO_ADDRESS_REGEX.matches(input) -> {
PaymentRecipient.CardanoAddress(input)
}
else -> null
}
}
fun isPartialPayCommand(input: String): Boolean {
val trimmed = input.trim().lowercase()
return trimmed.startsWith("/pay") || "/pay".startsWith(trimmed.ifEmpty { "/" })
}
}
Modify: libraries/textcomposer/impl/src/main/kotlin/io/element/android/libraries/textcomposer/mentions/ResolvedSuggestion.kt
Add new type:
// Add to sealed interface ResolvedSuggestion:
data class Command(
val command: String,
val description: String,
) : ResolvedSuggestion
Full diff:
sealed interface ResolvedSuggestion {
data class Member(...) : ResolvedSuggestion
data class Alias(...) : ResolvedSuggestion
+ data class Command(
+ val command: String,
+ val description: String,
+ ) : ResolvedSuggestion
}
Modify: features/messages/impl/src/main/kotlin/io/element/android/features/messages/impl/messagecomposer/suggestions/SuggestionsProcessor.kt
Replace empty command handling:
SuggestionType.Command,
-SuggestionType.Emoji,
-is SuggestionType.Custom -> {
- // Clear suggestions
- emptyList()
-}
+-> {
+ val commands = listOf(
+ ResolvedSuggestion.Command("/pay", "Send ADA to someone"),
+ )
+ commands.filter {
+ it.command.contains(suggestion.text, ignoreCase = true)
+ }
+}
+SuggestionType.Emoji,
+is SuggestionType.Custom -> {
+ emptyList()
+}
Modify: features/messages/impl/src/main/kotlin/io/element/android/features/messages/impl/messagecomposer/MessageComposerPresenter.kt
Add slash command interception in sendMessage:
// Add import at top:
import io.element.android.features.wallet.impl.slash.SlashCommandParser
// Inject parser:
@Inject
constructor(
// ... existing params ...
private val slashCommandParser: SlashCommandParser,
)
// In handleEvents(), find AnalyticsEvents.Composer.SendMessage handling:
// BEFORE sending to timeline, add:
when (val parseResult = slashCommandParser.parse(message.markdown)) {
is SlashCommandParser.ParseResult.Success -> {
when (val command = parseResult.command) {
is SlashCommand.Pay -> {
// Navigate to payment flow instead of sending
navigator.navigateToPaymentFlow(
roomId = room.roomId.value,
amount = command.amount,
unit = command.unit,
recipient = command.recipient,
)
return@launch
}
}
}
is SlashCommandParser.ParseResult.Error -> {
// Show error toast/snackbar
_state.value = _state.value.copy(
snackbarMessage = parseResult.message
)
return@launch
}
SlashCommandParser.ParseResult.NotACommand -> {
// Continue normal send flow
}
}
New: features/wallet/impl/src/main/kotlin/io/element/android/features/wallet/impl/slash/RecipientAddressResolver.kt
package io.element.android.features.wallet.impl.slash
import io.element.android.features.wallet.api.slash.PaymentRecipient
import io.element.android.libraries.matrix.api.room.MatrixRoom
import javax.inject.Inject
/**
* Resolves a Matrix user to a Cardano address.
*
* Phase 1: Returns null for Matrix users (address must be entered manually)
* Phase 2: Will query user's account data for published Cardano address
*/
class RecipientAddressResolver @Inject constructor() {
sealed class ResolveResult {
data class Resolved(val address: String) : ResolveResult()
object NeedsManualEntry : ResolveResult()
data class Error(val message: String) : ResolveResult()
}
suspend fun resolve(
recipient: PaymentRecipient,
room: MatrixRoom,
): ResolveResult {
return when (recipient) {
is PaymentRecipient.CardanoAddress -> {
// Validate address format
if (isValidCardanoAddress(recipient.address)) {
ResolveResult.Resolved(recipient.address)
} else {
ResolveResult.Error("Invalid Cardano address format")
}
}
is PaymentRecipient.MatrixUser -> {
// Phase 1: We can't resolve Matrix user to Cardano address
// User will need to enter address manually in payment UI
ResolveResult.NeedsManualEntry
}
}
}
private fun isValidCardanoAddress(address: String): Boolean {
// Basic validation: mainnet addresses start with addr1
// More thorough validation happens in TransactionBuilder
return address.startsWith("addr1") && address.length >= 50
}
}
Key Implementation Details
-
Syntax:
/pay <amount> <unit> <recipient>- Amount: decimal number (e.g.,
10,5.5) - Unit:
ADAorlovelace(case-insensitive) - Recipient:
@user:serveroraddr1...
- Amount: decimal number (e.g.,
-
Suggestions: When user types
/, show "pay" as autocomplete option -
Interception point: In
MessageComposerPresenter.sendMessage(), check if message is a slash command BEFORE sending to timeline -
Matrix user resolution: Phase 1 doesn't resolve
@userto address — payment UI will prompt for address entry
Gotchas
- Partial commands:
/pashouldn't error — user is still typing - Case sensitivity: Commands should be case-insensitive (
/PAY=/pay) - Whitespace: Handle multiple spaces between tokens
- Address validation: Basic format check in parser; full validation in TransactionBuilder
- Room context: Payment requires room context to resolve @mentions to actual user IDs
- Edit prevention: Don't allow editing messages that were slash commands (they didn't actually send)
Task 6: Payment Flow UI
Blocks: Task 7 (Payment Card)
Blocked by: Tasks 4, 5
Effort: 3 days
Acceptance criteria:
- Confirmation screen shows recipient, amount, fee estimate
- Manual address entry field when recipient is @user
- "Confirm" triggers biometric authentication
- Success state shows tx hash
- Error states display appropriate messages
- "Cancel" returns to composer
- Loading state during tx submission
- All states match Element X design patterns
Files
New: features/wallet/impl/src/main/kotlin/io/element/android/features/wallet/impl/payment/PaymentFlowState.kt
package io.element.android.features.wallet.impl.payment
import io.element.android.features.wallet.api.slash.PaymentRecipient
import io.element.android.features.wallet.api.slash.PaymentUnit
data class PaymentFlowState(
val step: PaymentStep,
val amount: Double,
val unit: PaymentUnit,
val originalRecipient: PaymentRecipient,
val resolvedAddress: String?,
val addressInput: String,
val estimatedFee: Long?,
val estimatedFeeAda: String?,
val totalAmountAda: String?,
val senderAddress: String?,
val senderBalance: Long?,
val senderBalanceAda: String?,
val txHash: String?,
val error: PaymentError?,
val eventSink: (PaymentFlowEvent) -> Unit,
)
sealed interface PaymentStep {
object Loading : PaymentStep
object EnterAddress : PaymentStep // When @user can't be resolved
object Confirm : PaymentStep
object Authenticating : PaymentStep
object Submitting : PaymentStep
object Success : PaymentStep
object Error : PaymentStep
}
sealed interface PaymentError {
object InsufficientFunds : PaymentError
object InvalidAddress : PaymentError
object NetworkError : PaymentError
object AuthenticationFailed : PaymentError
object AuthenticationCancelled : PaymentError
data class TransactionFailed(val message: String) : PaymentError
}
sealed interface PaymentFlowEvent {
data class AddressChanged(val address: String) : PaymentFlowEvent
object ConfirmAddress : PaymentFlowEvent
object ConfirmPayment : PaymentFlowEvent
data class AuthenticationResult(val success: Boolean, val error: String?) : PaymentFlowEvent
object Cancel : PaymentFlowEvent
object DismissError : PaymentFlowEvent
object Done : PaymentFlowEvent
}
New: features/wallet/impl/src/main/kotlin/io/element/android/features/wallet/impl/payment/PaymentFlowPresenter.kt
package io.element.android.features.wallet.impl.payment
import androidx.compose.runtime.*
import dagger.assisted.Assisted
import dagger.assisted.AssistedFactory
import dagger.assisted.AssistedInject
import io.element.android.features.wallet.api.slash.PaymentRecipient
import io.element.android.features.wallet.api.slash.PaymentUnit
import io.element.android.features.wallet.impl.cardano.CardanoClient
import io.element.android.features.wallet.impl.cardano.CardanoWalletManager
import io.element.android.features.wallet.impl.cardano.TransactionBuildError
import io.element.android.features.wallet.impl.cardano.TransactionBuilder
import io.element.android.features.wallet.impl.storage.CardanoKeyStorage
import io.element.android.libraries.architecture.Presenter
import io.element.android.libraries.matrix.api.MatrixClient
import io.element.android.libraries.matrix.api.core.RoomId
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.launch
class PaymentFlowPresenter @AssistedInject constructor(
@Assisted private val roomId: RoomId,
@Assisted private val amount: Double,
@Assisted private val unit: PaymentUnit,
@Assisted private val recipient: PaymentRecipient,
private val matrixClient: MatrixClient,
private val walletManager: CardanoWalletManager,
private val keyStorage: CardanoKeyStorage,
private val transactionBuilder: TransactionBuilder,
private val cardanoClient: CardanoClient,
) : Presenter<PaymentFlowState> {
@AssistedFactory
interface Factory {
fun create(
roomId: RoomId,
amount: Double,
unit: PaymentUnit,
recipient: PaymentRecipient,
): PaymentFlowPresenter
}
@Composable
override fun present(): PaymentFlowState {
val scope = rememberCoroutineScope()
val sessionId = matrixClient.sessionId
var step by remember { mutableStateOf<PaymentStep>(PaymentStep.Loading) }
var resolvedAddress by remember { mutableStateOf<String?>(null) }
var addressInput by remember { mutableStateOf("") }
var estimatedFee by remember { mutableStateOf<Long?>(null) }
var senderAddress by remember { mutableStateOf<String?>(null) }
var senderBalance by remember { mutableStateOf<Long?>(null) }
var txHash by remember { mutableStateOf<String?>(null) }
var error by remember { mutableStateOf<PaymentError?>(null) }
// Initialize
LaunchedEffect(Unit) {
// Get sender address
val address = keyStorage.getBaseAddress(sessionId).getOrNull()
senderAddress = address
// Get balance
address?.let {
cardanoClient.getBalance(it).onSuccess { balance ->
senderBalance = balance
}
}
// Check recipient type
when (recipient) {
is PaymentRecipient.CardanoAddress -> {
resolvedAddress = recipient.address
addressInput = recipient.address
step = PaymentStep.Confirm
}
is PaymentRecipient.MatrixUser -> {
// Can't resolve in Phase 1 — need manual entry
step = PaymentStep.EnterAddress
}
}
// Estimate fee
val recipientAddr = resolvedAddress ?: "addr1qxck..." // dummy for estimation
transactionBuilder.estimateFee(
senderAddress = address ?: return@LaunchedEffect,
recipientAddress = recipientAddr,
amountLovelace = (amount * unit.lovelaceMultiplier).toLong(),
).onSuccess { fee ->
estimatedFee = fee
}
}
val amountLovelace = (amount * unit.lovelaceMultiplier).toLong()
val amountAda = amountLovelace / 1_000_000.0
val feeAda = estimatedFee?.let { it / 1_000_000.0 }
val totalAda = feeAda?.let { amountAda + it }
fun handleEvent(event: PaymentFlowEvent) {
when (event) {
is PaymentFlowEvent.AddressChanged -> {
addressInput = event.address
}
PaymentFlowEvent.ConfirmAddress -> {
if (isValidCardanoAddress(addressInput)) {
resolvedAddress = addressInput
step = PaymentStep.Confirm
} else {
error = PaymentError.InvalidAddress
}
}
PaymentFlowEvent.ConfirmPayment -> {
step = PaymentStep.Authenticating
}
is PaymentFlowEvent.AuthenticationResult -> {
if (event.success) {
step = PaymentStep.Submitting
scope.launch {
submitTransaction(
scope = scope,
sessionId = sessionId,
recipientAddress = resolvedAddress!!,
amountLovelace = amountLovelace,
onSuccess = { hash ->
txHash = hash
step = PaymentStep.Success
},
onError = { err ->
error = err
step = PaymentStep.Error
}
)
}
} else {
error = if (event.error?.contains("cancel", ignoreCase = true) == true) {
PaymentError.AuthenticationCancelled
} else {
PaymentError.AuthenticationFailed
}
step = PaymentStep.Error
}
}
PaymentFlowEvent.Cancel -> {
// Navigator handles back
}
PaymentFlowEvent.DismissError -> {
error = null
step = PaymentStep.Confirm
}
PaymentFlowEvent.Done -> {
// Navigator handles finish
}
}
}
return PaymentFlowState(
step = step,
amount = amount,
unit = unit,
originalRecipient = recipient,
resolvedAddress = resolvedAddress,
addressInput = addressInput,
estimatedFee = estimatedFee,
estimatedFeeAda = feeAda?.let { "%.6f".format(it) },
totalAmountAda = totalAda?.let { "%.6f".format(it) },
senderAddress = senderAddress,
senderBalance = senderBalance,
senderBalanceAda = senderBalance?.let { "%.6f".format(it / 1_000_000.0) },
txHash = txHash,
error = error,
eventSink = ::handleEvent,
)
}
private suspend fun submitTransaction(
scope: CoroutineScope,
sessionId: io.element.android.libraries.matrix.api.core.SessionId,
recipientAddress: String,
amountLovelace: Long,
onSuccess: (String) -> Unit,
onError: (PaymentError) -> Unit,
) {
val result = walletManager.sendPayment(
sessionId = sessionId,
recipientAddress = recipientAddress,
amountLovelace = amountLovelace,
)
result.onSuccess { hash ->
// Send Matrix event
scope.launch {
sendPaymentEvent(
txHash = hash,
recipientAddress = recipientAddress,
amountLovelace = amountLovelace,
)
}
onSuccess(hash)
}.onFailure { throwable ->
val paymentError = when (throwable) {
is TransactionBuildError.InsufficientFunds -> PaymentError.InsufficientFunds
is TransactionBuildError.InvalidAddress -> PaymentError.InvalidAddress
is TransactionBuildError.NoUtxosAvailable -> PaymentError.InsufficientFunds
else -> PaymentError.TransactionFailed(throwable.message ?: "Unknown error")
}
onError(paymentError)
}
}
private suspend fun sendPaymentEvent(
txHash: String,
recipientAddress: String,
amountLovelace: Long,
) {
// Send m.payment.cardano event to room - implemented in Task 8
val room = matrixClient.getRoom(roomId)
room?.let {
// PaymentEventSender handles this
}
}
private fun isValidCardanoAddress(address: String): Boolean {
return address.startsWith("addr1") && address.length >= 50
}
}
New: features/wallet/impl/src/main/kotlin/io/element/android/features/wallet/impl/payment/PaymentFlowScreen.kt
package io.element.android.features.wallet.impl.payment
import androidx.compose.foundation.layout.*
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Check
import androidx.compose.material.icons.filled.Close
import androidx.compose.material.icons.filled.Send
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import io.element.android.libraries.designsystem.components.button.BackButton
import io.element.android.libraries.designsystem.theme.components.*
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun PaymentFlowScreen(
state: PaymentFlowState,
onNavigateBack: () -> Unit,
onAuthenticateRequest: () -> Unit,
modifier: Modifier = Modifier,
) {
Scaffold(
topBar = {
TopAppBar(
title = { Text("Send Payment") },
navigationIcon = {
BackButton(onClick = {
state.eventSink(PaymentFlowEvent.Cancel)
onNavigateBack()
})
}
)
},
modifier = modifier,
) { padding ->
Box(
modifier = Modifier
.fillMaxSize()
.padding(padding)
) {
when (state.step) {
PaymentStep.Loading -> {
CircularProgressIndicator(
modifier = Modifier.align(Alignment.Center)
)
}
PaymentStep.EnterAddress -> {
EnterAddressContent(
state = state,
modifier = Modifier.fillMaxSize(),
)
}
PaymentStep.Confirm -> {
ConfirmContent(
state = state,
onConfirm = {
state.eventSink(PaymentFlowEvent.ConfirmPayment)
onAuthenticateRequest()
},
modifier = Modifier.fillMaxSize(),
)
}
PaymentStep.Authenticating -> {
AuthenticatingContent(
modifier = Modifier.fillMaxSize(),
)
}
PaymentStep.Submitting -> {
SubmittingContent(
modifier = Modifier.fillMaxSize(),
)
}
PaymentStep.Success -> {
SuccessContent(
txHash = state.txHash ?: "",
onDone = {
state.eventSink(PaymentFlowEvent.Done)
onNavigateBack()
},
modifier = Modifier.fillMaxSize(),
)
}
PaymentStep.Error -> {
ErrorContent(
error = state.error,
onRetry = { state.eventSink(PaymentFlowEvent.DismissError) },
onCancel = {
state.eventSink(PaymentFlowEvent.Cancel)
onNavigateBack()
},
modifier = Modifier.fillMaxSize(),
)
}
}
}
}
}
@Composable
private fun EnterAddressContent(
state: PaymentFlowState,
modifier: Modifier = Modifier,
) {
Column(
modifier = modifier.padding(16.dp),
verticalArrangement = Arrangement.spacedBy(16.dp),
) {
Text(
text = "Enter recipient's Cardano address",
style = MaterialTheme.typography.titleMedium,
)
when (val recipient = state.originalRecipient) {
is io.element.android.features.wallet.api.slash.PaymentRecipient.MatrixUser -> {
Text(
text = "Sending to ${recipient.userId.value}",
style = MaterialTheme.typography.bodyMedium,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
Text(
text = "Enter their Cardano address below:",
style = MaterialTheme.typography.bodySmall,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
}
else -> {}
}
OutlinedTextField(
value = state.addressInput,
onValueChange = { state.eventSink(PaymentFlowEvent.AddressChanged(it)) },
label = { Text("Cardano Address") },
placeholder = { Text("addr1q...") },
modifier = Modifier.fillMaxWidth(),
singleLine = true,
isError = state.error == PaymentError.InvalidAddress,
supportingText = if (state.error == PaymentError.InvalidAddress) {
{ Text("Invalid Cardano address") }
} else null,
)
Spacer(modifier = Modifier.weight(1f))
Button(
onClick = { state.eventSink(PaymentFlowEvent.ConfirmAddress) },
modifier = Modifier.fillMaxWidth(),
enabled = state.addressInput.isNotBlank(),
) {
Text("Continue")
}
}
}
@Composable
private fun ConfirmContent(
state: PaymentFlowState,
onConfirm: () -> Unit,
modifier: Modifier = Modifier,
) {
Column(
modifier = modifier.padding(16.dp),
verticalArrangement = Arrangement.spacedBy(16.dp),
) {
// Amount card
Card(
modifier = Modifier.fillMaxWidth(),
) {
Column(
modifier = Modifier.padding(16.dp),
horizontalAlignment = Alignment.CenterHorizontally,
) {
Text(
text = "Amount",
style = MaterialTheme.typography.labelMedium,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
Text(
text = "${state.amount} ${state.unit.symbol}",
style = MaterialTheme.typography.headlineLarge,
)
}
}
// Details
Card(
modifier = Modifier.fillMaxWidth(),
) {
Column(
modifier = Modifier.padding(16.dp),
verticalArrangement = Arrangement.spacedBy(8.dp),
) {
DetailRow("To", state.resolvedAddress?.take(20) + "..." ?: "Unknown")
DetailRow("Network Fee", state.estimatedFeeAda?.let { "~$it ADA" } ?: "Calculating...")
HorizontalDivider()
DetailRow(
"Total",
state.totalAmountAda?.let { "$it ADA" } ?: "Calculating...",
bold = true
)
}
}
// Balance warning
state.senderBalance?.let { balance ->
val amountLovelace = (state.amount * state.unit.lovelaceMultiplier).toLong()
val feeEstimate = state.estimatedFee ?: 200_000L
if (balance < amountLovelace + feeEstimate) {
Card(
colors = CardDefaults.cardColors(
containerColor = MaterialTheme.colorScheme.errorContainer
),
modifier = Modifier.fillMaxWidth(),
) {
Text(
text = "⚠️ Insufficient balance (${state.senderBalanceAda} ADA available)",
modifier = Modifier.padding(16.dp),
color = MaterialTheme.colorScheme.onErrorContainer,
)
}
}
}
Spacer(modifier = Modifier.weight(1f))
Button(
onClick = onConfirm,
modifier = Modifier.fillMaxWidth(),
) {
Icon(Icons.Default.Send, contentDescription = null)
Spacer(modifier = Modifier.width(8.dp))
Text("Confirm & Authenticate")
}
}
}
@Composable
private fun DetailRow(
label: String,
value: String,
bold: Boolean = false,
modifier: Modifier = Modifier,
) {
Row(
modifier = modifier.fillMaxWidth(),
horizontalArrangement = Arrangement.SpaceBetween,
) {
Text(
text = label,
style = if (bold) MaterialTheme.typography.titleMedium else MaterialTheme.typography.bodyMedium,
)
Text(
text = value,
style = if (bold) MaterialTheme.typography.titleMedium else MaterialTheme.typography.bodyMedium,
)
}
}
@Composable
private fun AuthenticatingContent(modifier: Modifier = Modifier) {
Box(modifier = modifier, contentAlignment = Alignment.Center) {
Column(horizontalAlignment = Alignment.CenterHorizontally) {
CircularProgressIndicator()
Spacer(modifier = Modifier.height(16.dp))
Text("Authenticate to continue...")
}
}
}
@Composable
private fun SubmittingContent(modifier: Modifier = Modifier) {
Box(modifier = modifier, contentAlignment = Alignment.Center) {
Column(horizontalAlignment = Alignment.CenterHorizontally) {
CircularProgressIndicator()
Spacer(modifier = Modifier.height(16.dp))
Text("Submitting transaction...")
}
}
}
@Composable
private fun SuccessContent(
txHash: String,
onDone: () -> Unit,
modifier: Modifier = Modifier,
) {
Column(
modifier = modifier.padding(16.dp),
horizontalAlignment = Alignment.CenterHorizontally,
verticalArrangement = Arrangement.Center,
) {
Icon(
Icons.Default.Check,
contentDescription = null,
tint = MaterialTheme.colorScheme.primary,
modifier = Modifier.size(64.dp),
)
Spacer(modifier = Modifier.height(16.dp))
Text(
text = "Payment Sent!",
style = MaterialTheme.typography.headlineMedium,
)
Spacer(modifier = Modifier.height(8.dp))
Text(
text = "Transaction: ${txHash.take(16)}...",
style = MaterialTheme.typography.bodySmall,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
Spacer(modifier = Modifier.height(24.dp))
Button(onClick = onDone) {
Text("Done")
}
}
}
@Composable
private fun ErrorContent(
error: PaymentError?,
onRetry: () -> Unit,
onCancel: () -> Unit,
modifier: Modifier = Modifier,
) {
Column(
modifier = modifier.padding(16.dp),
horizontalAlignment = Alignment.CenterHorizontally,
verticalArrangement = Arrangement.Center,
) {
Icon(
Icons.Default.Close,
contentDescription = null,
tint = MaterialTheme.colorScheme.error,
modifier = Modifier.size(64.dp),
)
Spacer(modifier = Modifier.height(16.dp))
Text(
text = "Payment Failed",
style = MaterialTheme.typography.headlineMedium,
)
Spacer(modifier = Modifier.height(8.dp))
Text(
text = when (error) {
PaymentError.InsufficientFunds -> "Not enough ADA in your wallet"
PaymentError.InvalidAddress -> "Invalid recipient address"
PaymentError.NetworkError -> "Network error. Please try again."
PaymentError.AuthenticationFailed -> "Authentication failed"
PaymentError.AuthenticationCancelled -> "Authentication cancelled"
is PaymentError.TransactionFailed -> error.message
null -> "Unknown error"
},
style = MaterialTheme.typography.bodyMedium,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
Spacer(modifier = Modifier.height(24.dp))
Row(horizontalArrangement = Arrangement.spacedBy(16.dp)) {
OutlinedButton(onClick = onCancel) {
Text("Cancel")
}
Button(onClick = onRetry) {
Text("Try Again")
}
}
}
}
New: features/wallet/impl/src/main/kotlin/io/element/android/features/wallet/impl/payment/PaymentFlowNode.kt
package io.element.android.features.wallet.impl.payment
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.fragment.app.FragmentActivity
import com.bumble.appyx.core.modality.BuildContext
import com.bumble.appyx.core.node.Node
import com.bumble.appyx.core.plugin.Plugin
import dagger.assisted.Assisted
import dagger.assisted.AssistedFactory
import dagger.assisted.AssistedInject
import io.element.android.anvilannotations.ContributesNode
import io.element.android.features.wallet.api.slash.PaymentRecipient
import io.element.android.features.wallet.api.slash.PaymentUnit
import io.element.android.features.wallet.impl.biometric.BiometricAuthenticator
import io.element.android.libraries.architecture.NodeInputs
import io.element.android.libraries.architecture.inputs
import io.element.android.libraries.di.SessionScope
import io.element.android.libraries.matrix.api.core.RoomId
import kotlinx.coroutines.launch
@ContributesNode(SessionScope::class)
class PaymentFlowNode @AssistedInject constructor(
@Assisted buildContext: BuildContext,
@Assisted plugins: List<Plugin>,
private val presenterFactory: PaymentFlowPresenter.Factory,
private val biometricAuthenticator: BiometricAuthenticator,
) : Node(buildContext, plugins = plugins) {
data class Inputs(
val roomId: RoomId,
val amount: Double,
val unit: PaymentUnit,
val recipient: PaymentRecipient,
) : NodeInputs
private val inputs: Inputs = inputs()
private val presenter by lazy {
presenterFactory.create(
roomId = inputs.roomId,
amount = inputs.amount,
unit = inputs.unit,
recipient = inputs.recipient,
)
}
@Composable
override fun View(modifier: Modifier) {
val state = presenter.present()
PaymentFlowScreen(
state = state,
onNavigateBack = { navigateUp() },
onAuthenticateRequest = {
lifecycleScope.launch {
val activity = requireActivity() as FragmentActivity
val result = biometricAuthenticator.authenticate(
activity = activity,
title = "Confirm Payment",
subtitle = "Authenticate to send ${state.amount} ${state.unit.symbol}",
)
when (result) {
BiometricAuthenticator.AuthResult.Success -> {
state.eventSink(PaymentFlowEvent.AuthenticationResult(true, null))
}
is BiometricAuthenticator.AuthResult.Error -> {
state.eventSink(PaymentFlowEvent.AuthenticationResult(false, result.message))
}
BiometricAuthenticator.AuthResult.Cancelled -> {
state.eventSink(PaymentFlowEvent.AuthenticationResult(false, "cancelled"))
}
}
}
},
modifier = modifier,
)
}
@AssistedFactory
interface Factory {
fun create(
buildContext: BuildContext,
plugins: List<Plugin>,
): PaymentFlowNode
}
}
Key Implementation Details
- State machine: Loading → EnterAddress (if needed) → Confirm → Authenticating → Submitting → Success/Error
- Biometric trigger: Called from Node when entering
Authenticatingstep - Presenter pattern: Follows Element X conventions with
@Composable present()returning state - AssistedInject: Presenter uses
@AssistedInjectfor parameters that vary per instance - Event sink pattern: State includes
eventSinkfunction for handling events (Element X standard pattern) - Node pattern: Uses Appyx for navigation,
@ContributesNodefor DI
Gotchas
- Activity context for biometrics: Need
FragmentActivityfrom the node, not Application context - Lifecycle scope: Biometric callback must complete even if composition changes
- Back handling: Cancel must clean up state and navigate back
- Fee estimation timing: Estimate immediately on load; update if address changes
- Keyboard handling: Address input should show appropriate keyboard, dismiss on confirm
Task 7: Payment Card Timeline Item
Blocks: Nothing
Blocked by: Tasks 1, 6, 8
Effort: 2.5 days
Acceptance criteria:
m.payment.cardanoevent sends to room via raw event API- Payment card renders for sender
- Payment card renders for recipient
- Card shows amount, status, explorer link
- Tapping explorer link opens CardanoScan
- PENDING status updates to CONFIRMED (polling)
- Unknown/old clients see event as unknown (graceful degradation)
Files
New: features/wallet/api/src/main/kotlin/io/element/android/features/wallet/api/timeline/PaymentEventContent.kt
package io.element.android.features.wallet.api.timeline
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
/**
* Content for m.payment.cardano custom events.
*
* This is a proper custom event type, NOT a message with custom msgtype.
* Other clients will see it as an unknown event and gracefully degrade.
*
* Example JSON content:
* {
* "chain": "cardano",
* "network": "mainnet",
* "tx_hash": "abc123...",
* "sender_address": "addr1q...",
* "recipient_address": "addr1q...",
* "amount_lovelace": "10000000",
* "status": "pending",
* "fallback_text": "Sent 10 ADA"
* }
*/
@Serializable
data class PaymentEventContent(
@SerialName("chain")
val chain: String = "cardano",
@SerialName("network")
val network: String = "mainnet",
@SerialName("tx_hash")
val txHash: String?,
@SerialName("sender_address")
val senderAddress: String,
@SerialName("recipient_address")
val recipientAddress: String,
@SerialName("amount_lovelace")
val amountLovelace: String, // String to avoid precision issues
@SerialName("status")
val status: String, // "pending", "confirmed", "failed"
@SerialName("fallback_text")
val fallbackText: String, // Human-readable fallback
)
New: features/wallet/impl/src/main/kotlin/io/element/android/features/wallet/impl/timeline/TimelineItemPaymentContent.kt
package io.element.android.features.wallet.impl.timeline
import io.element.android.features.messages.impl.timeline.model.event.TimelineItemEventContent
data class TimelineItemPaymentContent(
val txHash: String?,
val senderAddress: String,
val recipientAddress: String,
val amountLovelace: Long,
val amountAda: String,
val status: PaymentStatus,
val network: String,
val isMine: Boolean, // Did current user send this?
) : TimelineItemEventContent {
override val type: String = "m.payment.cardano"
}
enum class PaymentStatus {
PENDING,
CONFIRMED,
FAILED,
}
New: features/wallet/impl/src/main/kotlin/io/element/android/features/wallet/impl/timeline/TimelineItemPaymentView.kt
package io.element.android.features.wallet.impl.timeline
import android.content.Intent
import android.net.Uri
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.*
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.ArrowOutward
import androidx.compose.material.icons.filled.CheckCircle
import androidx.compose.material.icons.filled.Error
import androidx.compose.material.icons.filled.Schedule
import androidx.compose.material3.*
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
@Composable
fun TimelineItemPaymentView(
content: TimelineItemPaymentContent,
modifier: Modifier = Modifier,
) {
val context = LocalContext.current
Card(
modifier = modifier.widthIn(max = 280.dp),
colors = CardDefaults.cardColors(
containerColor = MaterialTheme.colorScheme.secondaryContainer
),
) {
Column(
modifier = Modifier.padding(12.dp),
) {
// Header row
Row(
verticalAlignment = Alignment.CenterVertically,
horizontalArrangement = Arrangement.spacedBy(8.dp),
) {
// Cardano logo placeholder
Text(
text = "₳",
style = MaterialTheme.typography.titleLarge,
color = MaterialTheme.colorScheme.primary,
)
Text(
text = if (content.isMine) "Payment Sent" else "Payment Received",
style = MaterialTheme.typography.labelLarge,
)
Spacer(modifier = Modifier.weight(1f))
// Status icon
when (content.status) {
PaymentStatus.PENDING -> Icon(
Icons.Default.Schedule,
contentDescription = "Pending",
tint = MaterialTheme.colorScheme.onSurfaceVariant,
modifier = Modifier.size(16.dp),
)
PaymentStatus.CONFIRMED -> Icon(
Icons.Default.CheckCircle,
contentDescription = "Confirmed",
tint = MaterialTheme.colorScheme.primary,
modifier = Modifier.size(16.dp),
)
PaymentStatus.FAILED -> Icon(
Icons.Default.Error,
contentDescription = "Failed",
tint = MaterialTheme.colorScheme.error,
modifier = Modifier.size(16.dp),
)
}
}
Spacer(modifier = Modifier.height(8.dp))
// Amount
Text(
text = "${content.amountAda} ADA",
style = MaterialTheme.typography.headlineSmall,
fontWeight = FontWeight.Bold,
)
Spacer(modifier = Modifier.height(4.dp))
// Address (truncated)
Text(
text = if (content.isMine) {
"To: ${content.recipientAddress.take(12)}...${content.recipientAddress.takeLast(8)}"
} else {
"From: ${content.senderAddress.take(12)}...${content.senderAddress.takeLast(8)}"
},
style = MaterialTheme.typography.bodySmall,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
// Explorer link
content.txHash?.let { hash ->
Spacer(modifier = Modifier.height(8.dp))
Row(
modifier = Modifier
.clickable {
val url = "https://cardanoscan.io/transaction/$hash"
val intent = Intent(Intent.ACTION_VIEW, Uri.parse(url))
context.startActivity(intent)
}
.padding(vertical = 4.dp),
verticalAlignment = Alignment.CenterVertically,
) {
Text(
text = "View on CardanoScan",
style = MaterialTheme.typography.labelMedium,
color = MaterialTheme.colorScheme.primary,
)
Icon(
Icons.Default.ArrowOutward,
contentDescription = null,
tint = MaterialTheme.colorScheme.primary,
modifier = Modifier.size(14.dp),
)
}
}
}
}
}
New: features/wallet/impl/src/main/kotlin/io/element/android/features/wallet/impl/timeline/TimelineItemPaymentFactory.kt
package io.element.android.features.wallet.impl.timeline
import io.element.android.features.wallet.api.timeline.PaymentEventContent
import io.element.android.libraries.matrix.api.core.UserId
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonObject
import javax.inject.Inject
class TimelineItemPaymentFactory @Inject constructor(
private val json: Json,
) {
/**
* Creates a payment content item from raw event JSON.
* Called when the timeline factory encounters UnknownContent with
* event type "m.payment.cardano".
*/
fun createFromRaw(
rawJson: JsonObject,
currentUserId: UserId,
senderUserId: UserId,
): TimelineItemPaymentContent? {
return try {
val content = json.decodeFromJsonElement(
PaymentEventContent.serializer(),
rawJson
)
val amountLovelace = content.amountLovelace.toLongOrNull() ?: return null
val amountAda = "%.6f".format(amountLovelace / 1_000_000.0)
.trimEnd('0')
.trimEnd('.')
val status = when (content.status.lowercase()) {
"pending" -> PaymentStatus.PENDING
"confirmed" -> PaymentStatus.CONFIRMED
"failed" -> PaymentStatus.FAILED
else -> PaymentStatus.PENDING
}
TimelineItemPaymentContent(
txHash = content.txHash,
senderAddress = content.senderAddress,
recipientAddress = content.recipientAddress,
amountLovelace = amountLovelace,
amountAda = amountAda,
status = status,
network = content.network,
isMine = senderUserId == currentUserId,
)
} catch (e: Exception) {
null
}
}
}
New: features/wallet/impl/src/main/kotlin/io/element/android/features/wallet/impl/timeline/PaymentStatusPoller.kt
package io.element.android.features.wallet.impl.timeline
import io.element.android.features.wallet.impl.cardano.CardanoClient
import kotlinx.coroutines.*
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import javax.inject.Inject
import javax.inject.Singleton
/**
* Polls Koios to update payment status from PENDING to CONFIRMED.
* Updates local state when status changes.
*/
@Singleton
class PaymentStatusPoller @Inject constructor(
private val cardanoClient: CardanoClient,
) {
private val scope = CoroutineScope(Dispatchers.IO + SupervisorJob())
private val _pendingPayments = MutableStateFlow<Set<String>>(emptySet())
val pendingPayments: StateFlow<Set<String>> = _pendingPayments
private val _confirmedPayments = MutableStateFlow<Map<String, Long>>(emptyMap())
val confirmedPayments: StateFlow<Map<String, Long>> = _confirmedPayments
fun startPolling(txHash: String) {
if (txHash in _pendingPayments.value) return
_pendingPayments.value = _pendingPayments.value + txHash
scope.launch {
var confirmed = false
var attempts = 0
val maxAttempts = 60 // Poll for ~10 minutes
while (!confirmed && attempts < maxAttempts) {
delay(10_000) // 10 seconds between polls
attempts++
val result = cardanoClient.getTransactionStatus(txHash)
result.onSuccess { status ->
if (status.confirmed) {
confirmed = true
_pendingPayments.value = _pendingPayments.value - txHash
_confirmedPayments.value = _confirmedPayments.value +
(txHash to (status.blockHeight ?: 0L))
}
}
}
if (!confirmed) {
_pendingPayments.value = _pendingPayments.value - txHash
}
}
}
fun stopAll() {
scope.coroutineContext.cancelChildren()
_pendingPayments.value = emptySet()
}
}
Modify: features/messages/impl/src/main/kotlin/io/element/android/features/messages/impl/timeline/factories/event/TimelineItemContentFactory.kt
Add payment event handling in the UnknownContent branch:
// Add import:
import io.element.android.features.wallet.impl.timeline.TimelineItemPaymentFactory
// Inject factory:
@Inject constructor(
// ... existing ...
private val paymentFactory: TimelineItemPaymentFactory,
)
// In create() method, modify UnknownContent handling:
is UnknownContent -> {
// Check if this is a payment event we can handle
if (content.eventType == "m.payment.cardano") {
content.rawJson?.let { rawJson ->
paymentFactory.createFromRaw(rawJson, currentUserId, senderUserId)
} ?: TimelineItemUnknownContent
} else {
TimelineItemUnknownContent
}
}
Modify: features/messages/impl/src/main/kotlin/io/element/android/features/messages/impl/timeline/components/event/TimelineItemEventContentView.kt
Add payment case:
// Add import:
import io.element.android.features.wallet.impl.timeline.TimelineItemPaymentContent
import io.element.android.features.wallet.impl.timeline.TimelineItemPaymentView
// In the when block:
is TimelineItemPaymentContent -> TimelineItemPaymentView(
content = content,
modifier = modifier,
)
New: features/wallet/impl/src/main/kotlin/io/element/android/features/wallet/impl/room/PaymentEventSender.kt
package io.element.android.features.wallet.impl.room
import io.element.android.features.wallet.api.timeline.PaymentEventContent
import io.element.android.libraries.matrix.api.room.MatrixRoom
import kotlinx.serialization.encodeToString
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.encodeToJsonElement
import javax.inject.Inject
class PaymentEventSender @Inject constructor(
private val json: Json,
) {
companion object {
const val EVENT_TYPE = "m.payment.cardano"
}
suspend fun sendPaymentEvent(
room: MatrixRoom,
txHash: String,
senderAddress: String,
recipientAddress: String,
amountLovelace: Long,
): Result<String> {
val amountAda = "%.6f".format(amountLovelace / 1_000_000.0)
.trimEnd('0')
.trimEnd('.')
val content = PaymentEventContent(
txHash = txHash,
senderAddress = senderAddress,
recipientAddress = recipientAddress,
amountLovelace = amountLovelace.toString(),
status = "pending",
fallbackText = "Sent $amountAda ADA",
)
val contentJson = json.encodeToJsonElement(content) as JsonObject
// Send as raw custom event type
return room.sendRawEvent(
eventType = EVENT_TYPE,
content = contentJson,
)
}
}
Key Implementation Details
- Custom event type:
m.payment.cardanosent viaroom.sendRawEvent() - No formatted_body hack: Proper custom event type, not smuggled in message content
- UnknownContent interception: Timeline factory checks event type and parses raw JSON
- Graceful degradation: Other clients see it as an unknown event (not a broken message)
- Status tracking: Initially "pending", updated via polling
- Explorer URL: CardanoScan for mainnet:
https://cardanoscan.io/transaction/{txHash}
Gotchas
- Raw JSON access: Need to access
rawJsonfrom UnknownContent — verify SDK exposes this - Event editing: Updating status requires event relations. For MVP, track locally.
- Cross-client rendering: Other Matrix clients will simply not render the event (graceful)
- Network switch:
networkfield should match (mainnet vs testnet). Don't mix. - Amount precision: Store as string to avoid floating point issues with lovelace.
Task 8: SDK Extension — Raw Event Support for m.payment.cardano
Blocks: Task 7 (fully functional)
Blocked by: Task 1
Effort: 1.5 days
Acceptance criteria:
- SDK can send raw events with custom type via
sendRawEvent() - SDK returns raw JSON content for UnknownContent events
- Event parsing doesn't crash on unknown content
- Existing message types unaffected
Analysis: Current SDK Capabilities
The matrix-rust-sdk (used by Element X) handles custom events via UnknownContent. Key questions:
- Sending raw events: Does
MatrixRoomexposesendRawEvent()or equivalent? - Receiving raw JSON: Does
UnknownContentexpose the raw JSON content?
Approach: Verify and Extend as Needed
Step 1: Check existing API
In libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/room/MatrixRoom.kt:
interface MatrixRoom {
// Look for:
suspend fun sendRawEvent(eventType: String, content: JsonObject): Result<String>
// or similar
}
Step 2: Check UnknownContent
In SDK bindings, check if UnknownContent has:
data class UnknownContent(
val eventType: String,
val rawJson: JsonObject?, // Do we have access to this?
)
Implementation Path A: API Already Exists
If the SDK already exposes these methods (likely), we just need to:
- Use
sendRawEvent()in PaymentEventSender - Access
rawJsonin TimelineItemContentFactory
Implementation Path B: Minimal SDK Extension
If raw event sending isn't exposed:
// In RustMatrixRoom (or via extension)
suspend fun sendRawEvent(eventType: String, content: JsonObject): Result<String> {
return runCatching {
// The Rust SDK has this capability internally
innerRoom.sendRawEvent(eventType, content.toString())
}
}
Files to Verify/Modify
Check: libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/room/MatrixRoom.kt
Verify these methods exist or add them:
interface MatrixRoom {
// ... existing methods ...
/**
* Send a raw event with custom event type and content.
* @param eventType The event type (e.g., "m.payment.cardano")
* @param content The event content as JSON
* @return The event ID of the sent event
*/
suspend fun sendRawEvent(eventType: String, content: JsonObject): Result<String>
}
Check: libraries/matrix/impl/src/main/kotlin/io/element/android/libraries/matrix/impl/room/RustMatrixRoom.kt
Verify or add implementation:
override suspend fun sendRawEvent(eventType: String, content: JsonObject): Result<String> {
return runCatching {
innerRoom.sendRaw(eventType, content.toString()).await()
}.mapCatching { it.eventId.value }
}
Check: UnknownContent access to raw JSON
In timeline item mapping, verify we can access raw content:
// TimelineEventContentMapper.kt or similar
is TimelineItemContent.UnknownContent -> {
// Need access to:
content.eventType // The custom event type
content.rawJson // The raw JSON content
}
Key Implementation Details
- Raw event API: Use SDK's raw event capability, not message hacks
- No Rust SDK fork: Use existing Kotlin bindings
- JSON handling: Use kotlinx.serialization for JSON
- Event type:
m.payment.cardanois our custom type namespace
Gotchas
- SDK version: Verify against current Element X SDK version
- Breaking changes: If SDK updates, verify raw event API still works
- Type safety: Raw JSON loses type safety — validate carefully
- Event size limits: Matrix has event size limits (~65KB). Payment events are small.
Summary: Build Order
Week 1:
├── Task 1: Module Scaffolding (1 day) ─────────┐
├── Task 8: SDK Extension (1.5 days) ───────────┤
└── Task 2: Key Storage (3 days) ───────────────┤
│
Week 2: │
├── Task 3: Koios Client (1 day) ───────────────┤
├── Task 4: Transaction Builder (3 days) ←──────┘
└── Task 5: Slash Command (2 days)
Week 3:
├── Task 6: Payment Flow UI (3 days)
└── Task 7: Payment Card (2.5 days)
Buffer: 2 days for integration testing and bug fixes
Total Estimate: 17 working days (~3.5 weeks)
Changes from Previous Version
Correction 1: Koios Instead of Blockfrost
- Replaced all Blockfrost references with Koios
- Using
BackendFactory.getKoiosBackendService(Constants.KOIOS_MAINNET_URL) - No API key required — Koios public API is free
- Same interface — all transaction building code unchanged
- Removed:
BLOCKFROST_PROJECT_ID,blockfrost_project_idinjection, BlockfrostConfig
Correction 2: Raw Event Handling Instead of formatted_body Hack
- Using
room.sendRawEvent(eventType, content)for sending - Using
UnknownContent.rawJsoninterception for receiving - Proper custom event type:
m.payment.cardano - No data smuggled in formatted_body
- Graceful degradation: other clients see unknown event
- Zero Rust SDK changes or forks required
Framework Alignment Fixes
PaymentFlowPresenternow uses@AssistedInject+@AssistedFactoryfor runtime parameters- State uses
eventSink: (Event) -> Unitpattern (Element X standard) - Events are sealed interface with data classes (not interface with methods)
- Removed
PaymentFlowEventsinterface in favor of event sink pattern PaymentStatusPolleris@Singletonscoped- Fixed
Divider()→HorizontalDivider()(Material 3)
Post-MVP: Phase 2 Teasers
- SSSS Integration: Store encrypted wallet seed in Matrix account data
- Cross-device sync: Restore wallet on new device after verification
- Recipient address lookup: Query recipient's published Cardano address from their Matrix profile
- Balance widget: Show wallet balance in room header
- Transaction history: Query and display past payments
- Multi-asset support: Handle native tokens
Document prepared for Element X ADA project. Ready for implementation.