DustLocalState

JNI bridge to Midnight's Rust DustLocalState for managing dust wallet state.

Architecture:

Kotlin (Android) → JNI → Rust FFI → Midnight Ledger (Rust)

What is DustLocalState? DustLocalState is the core wallet state that tracks all dust UTXOs (tokens) for fee payments. It maintains:

• All registered dust tokens

• Dust generation progress over time

• Spending history

• Balance calculations

Value Units (IMPORTANT): The Midnight dust system uses different units for different purposes:

• Specks: Smallest dust unit (balance, initial_value)

• 1 Dust = 1,000,000 Specks

• Used for dust token values and balances

• Stars: Night (native token) unit

• 1 NIGHT = 1,000,000 Stars

• Used for backing Night UTXO values that generate dust

• Dust vs Night: These are DIFFERENT tokens with DIFFERENT units!

• Dust is generated FROM Night tokens over time

• Dust is used to pay transaction fees

Thread Safety: This class is NOT thread-safe. Do not share instances across threads. Each thread should create its own instance or use external synchronization.

Memory Safety: This class manages native memory and MUST be explicitly closed to prevent leaks. Use try-with-resources or finally blocks:

val state = DustLocalState.create()
try {
    val balance = state.getBalance(System.currentTimeMillis())
    println("Balance: $balance Specks")
} finally {
    state.close()
}

Usage:

// Create new state
val state = DustLocalState.create() ?: error("Failed to create state")
try {
    // Get current balance
    val now = System.currentTimeMillis()
    val balance = state.getBalance(now)
    println("Current balance: $balance Specks")

    // Serialize state for storage
    val serialized = state.serialize()
    database.saveState(serialized)
} finally {
    state.close()
}

Native Library: This class loads libkuira_crypto_ffi.so (Android) which is compiled from:

• Location: kuira-crypto-ffi/

• Dependencies: midnight-ledger (version-abstract FFI — see Cargo.toml)

References:

• Rust FFI: kuira-crypto-ffi/src/dust_ffi.rs

• Dust Spec: midnight-libraries/midnight-ledger/spec/dust.md