indexer/com.midnight.kuira.core.indexer.utxo/UtxoManager

UtxoManager

class UtxoManager(utxoDao: UnshieldedUtxoDao)

Manages UTXO state from transaction updates.

Handles:

Processing transaction updates (created/spent UTXOs)
Three-state UTXO lifecycle (AVAILABLE → PENDING → SPENT)
Transaction failure handling (unlock UTXOs)
Calculating balances from available UTXOs only

Transaction Status Handling:

SUCCESS/PARTIAL_SUCCESS: Create UTXOs (AVAILABLE), mark spent as SPENT
FAILURE: Don't create UTXOs, unlock spent UTXOs (PENDING → AVAILABLE)

Thread-safe: All operations are suspend functions using Room's built-in thread safety.

Constructors

UtxoManager

constructor(utxoDao: UnshieldedUtxoDao)

Types

ProcessingResult

sealed class ProcessingResult

Result of processing a transaction update.

Functions

calculateBalance

suspend fun calculateBalance(address: String): Map<String, BigInteger>

Calculate balance for an address.

clearUtxos

suspend fun clearUtxos(address: String)

Delete all UTXOs for an address.

debugDumpAllUtxos

suspend fun debugDumpAllUtxos(address: String, tag: String)

Debug: Dump all UTXOs for an address to logs.

getUnspentUtxos

suspend fun getUnspentUtxos(address: String): List<UnshieldedUtxoEntity>

Get detailed UTXO list for an address.

hasAnyUtxos

suspend fun hasAnyUtxos(address: String): Boolean

Check if database has ANY UTXOs for this address (any state).

hasAvailableUtxos

suspend fun hasAvailableUtxos(address: String): Boolean

Check if database has AVAILABLE UTXOs for this address.

markUtxosAsSpent

suspend fun markUtxosAsSpent(utxoIds: List<String>)

Mark UTXOs as spent by their database IDs.

markUtxosAsSpentByIntent

suspend fun markUtxosAsSpentByIntent(utxoIntentIds: List<Pair<String, Int>>, spentByLocalTx: Boolean = true): Int

Mark UTXOs as spent by their intent identifiers (intentHash + outputNo).

observeBalance

fun observeBalance(address: String): Flow<Map<String, BigInteger>>

Observe balance changes for an address (available UTXOs only).

observePendingBalance

fun observePendingBalance(address: String): Flow<Map<String, BigInteger>>

Observe pending balance for an address (locked in pending transactions).

observeUtxoCounts

fun observeUtxoCounts(address: String): Flow<Map<String, Int>>

Observe UTXO counts per token type (available UTXOs only).

processUpdate

suspend fun processUpdate(update: UnshieldedTransactionUpdate): UtxoManager.ProcessingResult

Process transaction update from subscription.

resetSpentUtxosForHealing

suspend fun resetSpentUtxosForHealing(address: String): Int

Reset ALL SPENT UTXOs to AVAILABLE for self-healing.

selectAndLockUtxos

suspend fun selectAndLockUtxos(address: String, tokenType: String, requiredAmount: BigInteger): UtxoSelector.SelectionResult

Select and lock UTXOs for transaction (atomic operation).

selectAndLockUtxosMultiToken

suspend fun selectAndLockUtxosMultiToken(address: String, requiredAmounts: Map<String, BigInteger>): UtxoSelector.MultiTokenResult

Select and lock UTXOs for multiple token types (atomic operation).

unlockUtxos

suspend fun unlockUtxos(utxoIds: List<String>)

Unlock UTXOs (mark as AVAILABLE).