diff --git a/amethyst/src/main/java/com/vitorpamplona/amethyst/model/AccountSettings.kt b/amethyst/src/main/java/com/vitorpamplona/amethyst/model/AccountSettings.kt index e2613fbe36..0ae9158a53 100644 --- a/amethyst/src/main/java/com/vitorpamplona/amethyst/model/AccountSettings.kt +++ b/amethyst/src/main/java/com/vitorpamplona/amethyst/model/AccountSettings.kt @@ -1221,7 +1221,8 @@ class AccountSettings( * Reserve [count] consecutive NUT-13 counters for [keysetId], * returning the first one. Caller derives `(secret, r)` from * `(seed, keysetId, i)` for `i in [returned .. returned+count-1]`. - * Persisted synchronously before returning — see [CashuKeysetCounterStore]. + * Persisted before returning — see [CashuKeysetCounterStore]. Suspends + * because that write is what stands between a crash and a reused counter. * * One-time migration: when this keyset has a non-zero value in the * legacy [cashuKeysetCounters] map (from a build that persisted @@ -1229,7 +1230,7 @@ class AccountSettings( * still at zero, the legacy value is copied over before we reserve * so an upgrade doesn't reset the counter. */ - fun reserveCashuCounters( + suspend fun reserveCashuCounters( keysetId: String, count: Int, ): Long { @@ -1238,12 +1239,12 @@ class AccountSettings( } /** Inspect the next counter for [keysetId] without consuming any. */ - fun peekCashuCounter(keysetId: String): Long { + suspend fun peekCashuCounter(keysetId: String): Long { migrateLegacyCashuCounter(keysetId) return cashuCounters.peek(keysetId) } - private fun migrateLegacyCashuCounter(keysetId: String) { + private suspend fun migrateLegacyCashuCounter(keysetId: String) { val legacy = cashuKeysetCounters[keysetId] ?: return cashuCounters.seedIfMissing(keysetId, legacy) } diff --git a/amethyst/src/main/java/com/vitorpamplona/amethyst/model/nip60Cashu/CashuPreferences.kt b/amethyst/src/main/java/com/vitorpamplona/amethyst/model/nip60Cashu/CashuPreferences.kt index 02ce5266ac..08f3b96ada 100644 --- a/amethyst/src/main/java/com/vitorpamplona/amethyst/model/nip60Cashu/CashuPreferences.kt +++ b/amethyst/src/main/java/com/vitorpamplona/amethyst/model/nip60Cashu/CashuPreferences.kt @@ -20,110 +20,64 @@ */ package com.vitorpamplona.amethyst.model.nip60Cashu -import android.annotation.SuppressLint import android.content.Context -import android.content.SharedPreferences -import androidx.core.content.edit +import androidx.datastore.preferences.core.PreferenceDataStoreFactory +import androidx.datastore.preferences.core.longPreferencesKey import com.vitorpamplona.amethyst.Amethyst import com.vitorpamplona.amethyst.commons.cashu.CashuKeysetCounterStore +import com.vitorpamplona.amethyst.commons.cashu.DataStoreCashuCounterStore +import com.vitorpamplona.amethyst.commons.model.preferences.CopyOnceMigration +import com.vitorpamplona.quartz.utils.cache.LargeCache +import okio.Path.Companion.toOkioPath +import java.io.File /** - * Per-account Cashu state that needs durable, synchronous persistence — - * separate from [com.vitorpamplona.amethyst.model.AccountSettings] which - * batches writes through a 1-second debounced StateFlow. + * Android's per-account NUT-13 counter store: the shared + * [DataStoreCashuCounterStore] over a file in the app's data directory. * - * # Why a separate store + * Two older layers feed into it, and neither may move a counter backwards: * - * The NUT-13 keyset counter is the critical bit. Every mint / swap / - * melt reserves counter slots, derives deterministic blinded outputs at - * those slots, sends them to the mint, and the mint signs them. The - * mint persists which (keyset, blind_message) pairs it has ever signed; - * a second request to sign the same blind_message returns HTTP 400 - * "outputs already signed". So once the wallet hands a counter to the - * mint, the local counter advance MUST survive a crash — otherwise the - * next reservation pulls the same slot and the mint rejects it. + * - `cashu_prefs_` SharedPreferences, copied in full on first read by + * [CopyOnceMigration]. The copy happens inside the same atomic DataStore + * write that records it happened, so a crash cannot leave the marker set + * with the counters missing. It is a copy, not a move: the old file stays + * intact, so a rolled-back build still finds its counters. + * - `AccountSettings.cashuKeysetCounters`, an older in-settings map, still + * applied per keyset through `seedIfMissing` on every read. * - * The default settings save path debounces writes by 1000 ms, which is - * exactly the race window between "we asked the mint to sign" and "the - * mint replied". A crash inside that window (OOM, signer dialog dismiss, - * unexpected process death) loses the counter advance and makes the - * wallet unusable. This store writes via `commit = true` so each - * reservation is durable before the function returns. - * - * # Layout - * - * One SharedPreferences file per account, named - * `cashu_prefs_.xml`. Keys are flat: - * - `counter_` → Long, the next free NUT-13 counter - * - * Plain (non-encrypted) prefs because keyset counters aren't secret — - * they're not the seed, they don't carry value, and a leak would only - * tell an attacker how many proofs the wallet has minted at each - * keyset (a privacy signal at most). - * - * # Migration - * - * Older builds stored counters inside `AccountSettings.cashuKeysetCounters`. - * On first read of a given keyset, callers should pre-seed the store - * from the legacy map (one-time copy) so an upgrade doesn't reset the - * counter to zero. See `AccountSettings.migrateCashuCountersTo` for - * the helper. + * Losing a counter here means restarting a keyset at zero and reusing + * indices, which costs real ecash — so nothing on this path is best-effort. */ -class CashuPreferences( - private val prefs: SharedPreferences, -) : CashuKeysetCounterStore { - /** Inspect the next free counter for [keysetId] without advancing it. */ - @Synchronized - override fun peek(keysetId: String): Long = prefs.getLong(counterKey(keysetId), 0L) +object CashuPreferences { + private const val LEGACY_FILE_PREFIX = "cashu_prefs_" + + private val stores = LargeCache() /** - * Atomically reserve [count] consecutive NUT-13 counters for - * [keysetId] and return the first reserved index. The write is - * forced to disk with `commit = true` BEFORE returning — see the - * class header for why this isn't optional. + * Per-account instance, cached: DataStore refuses two live instances over + * one file, and a second instance would defeat the single-writer + * serialisation that `reserve` depends on. */ - @Synchronized - @SuppressLint("ApplySharedPref") - override fun reserve( - keysetId: String, - count: Int, - ): Long { - require(count > 0) { "Counter reservation must be positive" } - val current = peek(keysetId) - val next = current + count.toLong() - prefs.edit(commit = true) { putLong(counterKey(keysetId), next) } - return current - } - - /** - * Seed [keysetId]'s counter from a legacy value found in - * [AccountSettings.cashuKeysetCounters]. No-op when the store - * already has a value at or above [legacyValue] — never moves the - * counter backwards. Called once at wallet load to carry forward - * pre-migration state. - */ - @Synchronized - @SuppressLint("ApplySharedPref") - override fun seedIfMissing( - keysetId: String, - legacyValue: Long, - ) { - if (legacyValue <= 0L) return - val current = peek(keysetId) - if (current >= legacyValue) return - prefs.edit(commit = true) { putLong(counterKey(keysetId), legacyValue) } - } - - companion object { - private const val FILE_PREFIX = "cashu_prefs_" - - private fun counterKey(keysetId: String) = "counter_$keysetId" - - /** Per-account instance. [npub] keys the on-disk file so each account is isolated. */ - fun forAccount(npub: String): CashuPreferences { + fun forAccount(npub: String): CashuKeysetCounterStore = + stores.getOrCreate(npub) { val context = Amethyst.instance.appContext - val prefs = context.getSharedPreferences("$FILE_PREFIX$npub", Context.MODE_PRIVATE) - return CashuPreferences(prefs) + DataStoreCashuCounterStore( + PreferenceDataStoreFactory.createWithPath( + migrations = listOf(legacyMigration(context, npub)), + produceFile = { File(context.filesDir, "datastore/cashu_$npub.preferences_pb").toOkioPath() }, + ), + ) + } + + private fun legacyMigration( + context: Context, + npub: String, + ) = CopyOnceMigration("migrated.cashuCounters") { out -> + val legacy = context.getSharedPreferences("$LEGACY_FILE_PREFIX$npub", Context.MODE_PRIVATE) + legacy.all.forEach { (key, value) -> + if (key.startsWith(DataStoreCashuCounterStore.COUNTER_PREFIX) && value is Long) { + out[longPreferencesKey(key)] = value + } } } } diff --git a/cli/src/main/kotlin/com/vitorpamplona/amethyst/cli/stores/FileCashuKeysetCounterStore.kt b/cli/src/main/kotlin/com/vitorpamplona/amethyst/cli/stores/FileCashuKeysetCounterStore.kt index c561cf2b10..02b3317824 100644 --- a/cli/src/main/kotlin/com/vitorpamplona/amethyst/cli/stores/FileCashuKeysetCounterStore.kt +++ b/cli/src/main/kotlin/com/vitorpamplona/amethyst/cli/stores/FileCashuKeysetCounterStore.kt @@ -54,9 +54,9 @@ class FileCashuKeysetCounterStore( Persisted() } - override fun peek(keysetId: String): Long = synchronized(lock) { load().keyset_counters[keysetId] ?: 0L } + override suspend fun peek(keysetId: String): Long = synchronized(lock) { load().keyset_counters[keysetId] ?: 0L } - override fun reserve( + override suspend fun reserve( keysetId: String, count: Int, ): Long = diff --git a/commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/cashu/CashuKeysetCounterStore.kt b/commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/cashu/CashuKeysetCounterStore.kt index 3974287c4d..64349e0b3f 100644 --- a/commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/cashu/CashuKeysetCounterStore.kt +++ b/commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/cashu/CashuKeysetCounterStore.kt @@ -27,7 +27,8 @@ package com.vitorpamplona.amethyst.commons.cashu * monotonically increasing counter. Reusing a counter makes the mint reply * `outputs already signed`, so every reservation MUST be persisted **before** * the blinded outputs hit the mint. Implementations therefore make - * [reserve] atomic and durable. + * [reserve] atomic and durable. They suspend because durable storage on + * every target this runs on is a suspending API. * * - Android backs this with `AccountSettings` / `CashuPreferences`. * - `amy` backs this with `~/.amy//cashu.json`. @@ -37,13 +38,13 @@ package com.vitorpamplona.amethyst.commons.cashu */ interface CashuKeysetCounterStore { /** The next counter for [keysetId] without advancing it (0 if unseen). */ - fun peek(keysetId: String): Long + suspend fun peek(keysetId: String): Long /** * Atomically reserve [count] consecutive counters for [keysetId] and * return the first reserved index. Persists before returning. */ - fun reserve( + suspend fun reserve( keysetId: String, count: Int, ): Long @@ -55,7 +56,7 @@ interface CashuKeysetCounterStore { * kept whatever the backing store; a host whose store can write the value in * one atomic op should override it. */ - fun seedIfMissing( + suspend fun seedIfMissing( keysetId: String, legacyValue: Long, ) { @@ -76,9 +77,9 @@ interface CashuKeysetCounterStore { object UnavailableCashuKeysetCounterStore : CashuKeysetCounterStore { private fun fail(): Nothing = error("No durable NUT-13 counter store is wired for this account; refusing to reuse counters.") - override fun peek(keysetId: String): Long = fail() + override suspend fun peek(keysetId: String): Long = fail() - override fun reserve( + override suspend fun reserve( keysetId: String, count: Int, ): Long = fail() diff --git a/commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/cashu/DataStoreCashuCounterStore.kt b/commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/cashu/DataStoreCashuCounterStore.kt new file mode 100644 index 0000000000..3795cd3a7a --- /dev/null +++ b/commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/cashu/DataStoreCashuCounterStore.kt @@ -0,0 +1,101 @@ +/* + * Copyright (c) 2025 Vitor Pamplona + * + * Permission is hereby granted, free of charge, to any person obtaining a copy of + * this software and associated documentation files (the "Software"), to deal in + * the Software without restriction, including without limitation the rights to use, + * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the + * Software, and to permit persons to whom the Software is furnished to do so, + * subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in all + * copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS + * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR + * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN + * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + */ +package com.vitorpamplona.amethyst.commons.cashu + +import androidx.datastore.core.DataStore +import androidx.datastore.preferences.core.Preferences +import androidx.datastore.preferences.core.edit +import androidx.datastore.preferences.core.emptyPreferences +import androidx.datastore.preferences.core.longPreferencesKey +import kotlinx.coroutines.flow.catch +import kotlinx.coroutines.flow.first +import okio.IOException + +/** + * DataStore-backed NUT-13 counter store, shared by every front end that has one. + * + * # Why the counters are not secret + * + * They are indices, not key material: they derive nothing without the wallet + * seed, carry no value, and a leak would at most reveal how many proofs the + * wallet has minted at each keyset. + * + * # Why every write is awaited + * + * Reusing a counter makes the mint reply `outputs already signed` and strands + * the proofs, so [reserve] must reach disk before the secrets derived from it + * reach the mint. DataStore's `edit` suspends until its write completes and + * swaps the file atomically — the same guarantee + * `SharedPreferences.edit(commit = true)` gave, paid at a suspension rather + * than a blocked thread. + * + * Read and write live inside one `edit`, so two concurrent mints cannot + * observe the same starting index; that is what the previous implementation's + * `@Synchronized` was for. + */ +class DataStoreCashuCounterStore( + private val store: DataStore, +) : CashuKeysetCounterStore { + companion object { + const val COUNTER_PREFIX = "counter_" + + fun counterKey(keysetId: String) = longPreferencesKey(COUNTER_PREFIX + keysetId) + } + + private suspend fun read(): Preferences = + store.data + .catch { e -> if (e is IOException) emit(emptyPreferences()) else throw e } + .first() + + override suspend fun peek(keysetId: String): Long = read()[counterKey(keysetId)] ?: 0L + + override suspend fun reserve( + keysetId: String, + count: Int, + ): Long { + require(count > 0) { "Counter reservation must be positive" } + var first = 0L + store.edit { prefs -> + val key = counterKey(keysetId) + first = prefs[key] ?: 0L + prefs[key] = first + count.toLong() + } + return first + } + + /** + * Carry a counter forward from an older store, never backwards. + * + * Writes the value directly in one atomic edit rather than advancing + * through [reserve], and compares inside that edit so a concurrent + * reservation cannot be undone by a stale read. + */ + override suspend fun seedIfMissing( + keysetId: String, + legacyValue: Long, + ) { + if (legacyValue <= 0L) return + store.edit { prefs -> + val key = counterKey(keysetId) + if ((prefs[key] ?: 0L) < legacyValue) prefs[key] = legacyValue + } + } +} diff --git a/commons/src/jvmAndroid/kotlin/com/vitorpamplona/amethyst/commons/cashu/ops/CashuWalletOps.kt b/commons/src/jvmAndroid/kotlin/com/vitorpamplona/amethyst/commons/cashu/ops/CashuWalletOps.kt index 99def91987..d7e7dd65bc 100644 --- a/commons/src/jvmAndroid/kotlin/com/vitorpamplona/amethyst/commons/cashu/ops/CashuWalletOps.kt +++ b/commons/src/jvmAndroid/kotlin/com/vitorpamplona/amethyst/commons/cashu/ops/CashuWalletOps.kt @@ -119,14 +119,14 @@ class CashuWalletOps( * it. Used to rewind the restore window in [completeMintFromLightning] * recovery. Default is 0 (no persistent counter store). */ - private val peekCashuCounter: (keysetId: String) -> Long = { 0L }, + private val peekCashuCounter: suspend (keysetId: String) -> Long = { 0L }, /** * Atomically reserve [count] consecutive NUT-13 counters and * return the first reserved index. Used by the recovery path to * advance past slots the mint confirmed in use. Default is a * no-op for tests / random-only callers. */ - private val reserveCashuCounters: (keysetId: String, count: Int) -> Long = { _, _ -> 0L }, + private val reserveCashuCounters: suspend (keysetId: String, count: Int) -> Long = { _, _ -> 0L }, ) { private val opsCache = ConcurrentHashMap() diff --git a/commons/src/jvmTest/kotlin/com/vitorpamplona/amethyst/commons/cashu/DataStoreCashuCounterStoreTest.kt b/commons/src/jvmTest/kotlin/com/vitorpamplona/amethyst/commons/cashu/DataStoreCashuCounterStoreTest.kt new file mode 100644 index 0000000000..e1485b0698 --- /dev/null +++ b/commons/src/jvmTest/kotlin/com/vitorpamplona/amethyst/commons/cashu/DataStoreCashuCounterStoreTest.kt @@ -0,0 +1,254 @@ +/* + * Copyright (c) 2025 Vitor Pamplona + * + * Permission is hereby granted, free of charge, to any person obtaining a copy of + * this software and associated documentation files (the "Software"), to deal in + * the Software without restriction, including without limitation the rights to use, + * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the + * Software, and to permit persons to whom the Software is furnished to do so, + * subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in all + * copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS + * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR + * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN + * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + */ +package com.vitorpamplona.amethyst.commons.cashu + +import androidx.datastore.core.DataMigration +import androidx.datastore.core.DataStore +import androidx.datastore.preferences.core.PreferenceDataStoreFactory +import androidx.datastore.preferences.core.Preferences +import androidx.datastore.preferences.core.longPreferencesKey +import com.vitorpamplona.amethyst.commons.model.preferences.CopyOnceMigration +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Dispatchers +import kotlinx.coroutines.SupervisorJob +import kotlinx.coroutines.async +import kotlinx.coroutines.awaitAll +import kotlinx.coroutines.cancelAndJoin +import kotlinx.coroutines.job +import kotlinx.coroutines.test.runTest +import okio.Path.Companion.toOkioPath +import org.junit.Assert.assertEquals +import org.junit.Assert.assertTrue +import org.junit.Rule +import org.junit.Test +import org.junit.rules.TemporaryFolder +import java.io.File + +/** + * NUT-13 counters decide whether ecash is spendable. + * + * A counter handed out twice under the same (seed, keyset) derives the same + * blinded secret twice; the mint answers `outputs already signed` and the + * proofs are stranded. These tests exist because that path had no coverage at + * all while it was backed by SharedPreferences. + */ +class DataStoreCashuCounterStoreTest { + @get:Rule + val folder = TemporaryFolder() + + private var seq = 0 + + /** + * Closes a store's scope and waits for it. + * + * DataStore refuses two live instances over one file and only releases it + * once the owning job has actually finished, so a bare cancel() races the + * next open. + */ + private suspend fun CoroutineScope.release() { + coroutineContext.job.cancelAndJoin() + } + + private fun raw( + file: File = File(folder.root, "cashu_${seq++}.preferences_pb"), + scope: CoroutineScope = CoroutineScope(Dispatchers.IO + SupervisorJob()), + migrations: List> = emptyList(), + ): DataStore = + PreferenceDataStoreFactory.createWithPath( + scope = scope, + migrations = migrations, + produceFile = { file.toOkioPath() }, + ) + + @Test + fun anUnseenKeysetStartsAtZero() = + runTest { + assertEquals(0L, DataStoreCashuCounterStore(raw()).peek("keyset1")) + } + + @Test + fun peekDoesNotAdvance() = + runTest { + val store = DataStoreCashuCounterStore(raw()) + + store.peek("keyset1") + store.peek("keyset1") + + assertEquals(0L, store.reserve("keyset1", 1)) + } + + @Test + fun reserveReturnsTheFirstIndexAndAdvancesByCount() = + runTest { + val store = DataStoreCashuCounterStore(raw()) + + assertEquals(0L, store.reserve("keyset1", 3)) + assertEquals(3L, store.peek("keyset1")) + assertEquals(3L, store.reserve("keyset1", 2)) + assertEquals(5L, store.peek("keyset1")) + } + + @Test + fun keysetsAdvanceIndependently() = + runTest { + val store = DataStoreCashuCounterStore(raw()) + + store.reserve("keyset1", 5) + + assertEquals(0L, store.reserve("keyset2", 1)) + } + + @Test + fun aNonPositiveReservationIsRejected() = + runTest { + val store = DataStoreCashuCounterStore(raw()) + + // Not assertThrows: a nested runTest would wrap the failure. + val thrown = runCatching { store.reserve("keyset1", 0) }.exceptionOrNull() + + assertTrue("expected IllegalArgumentException, got $thrown", thrown is IllegalArgumentException) + } + + /** + * The property everything else rests on: no index is ever handed out twice. + * Concurrent reservations must carve up disjoint ranges. + */ + @Test + fun concurrentReservationsNeverOverlap() = + runTest { + val store = DataStoreCashuCounterStore(raw()) + val batch = 4 + val workers = 25 + + val firsts = + (1..workers) + .map { async(Dispatchers.IO) { store.reserve("keyset1", batch) } } + .awaitAll() + + val handedOut = firsts.flatMap { first -> (0 until batch).map { first + it } } + assertEquals("every index handed out exactly once", handedOut.size, handedOut.toSet().size) + assertEquals("the counter accounts for all of them", (workers * batch).toLong(), store.peek("keyset1")) + } + + /** A reserved counter must survive the process that reserved it. */ + @Test + fun reservationsSurviveAReopen() = + runTest { + val file = File(folder.root, "persist.preferences_pb") + + val firstScope = CoroutineScope(Dispatchers.IO + SupervisorJob()) + DataStoreCashuCounterStore(raw(file, firstScope)).reserve("keyset1", 7) + firstScope.release() + + val secondScope = CoroutineScope(Dispatchers.IO + SupervisorJob()) + assertEquals(7L, DataStoreCashuCounterStore(raw(file, secondScope)).peek("keyset1")) + secondScope.release() + } + + // ── seeding from older stores ───────────────────────────────────── + + @Test + fun seedIfMissingCarriesALegacyValueForward() = + runTest { + val store = DataStoreCashuCounterStore(raw()) + + store.seedIfMissing("keyset1", 42L) + + assertEquals(42L, store.peek("keyset1")) + } + + /** Never backwards: a legacy value below the current one must be ignored. */ + @Test + fun seedIfMissingNeverMovesACounterBackwards() = + runTest { + val store = DataStoreCashuCounterStore(raw()) + store.reserve("keyset1", 100) + + store.seedIfMissing("keyset1", 5L) + + assertEquals(100L, store.peek("keyset1")) + } + + @Test + fun seedIfMissingIgnoresNonPositiveValues() = + runTest { + val store = DataStoreCashuCounterStore(raw()) + store.reserve("keyset1", 3) + + store.seedIfMissing("keyset1", 0L) + store.seedIfMissing("keyset1", -1L) + + assertEquals(3L, store.peek("keyset1")) + } + + /** + * The SharedPreferences -> DataStore migration. A counter lost here + * restarts a keyset at zero and reuses every index it already spent. + */ + @Test + fun theLegacyMigrationCarriesEveryCounter() = + runTest { + val legacy = + mapOf( + "counter_keysetA" to 17L, + "counter_keysetB" to 4L, + ) + val migration = + CopyOnceMigration("migrated.cashuCounters") { out -> + legacy.forEach { (key, value) -> out[longPreferencesKey(key)] = value } + } + + val store = DataStoreCashuCounterStore(raw(migrations = listOf(migration))) + + assertEquals(17L, store.peek("keysetA")) + assertEquals(4L, store.peek("keysetB")) + assertEquals("the next reservation continues, never replays", 17L, store.reserve("keysetA", 1)) + } + + /** The migration must not re-run and rewind counters spent since it ran. */ + @Test + fun theLegacyMigrationDoesNotRewindLaterReservations() = + runTest { + val file = File(folder.root, "once.preferences_pb") + val migration = { CopyOnceMigration("migrated.cashuCounters") { out -> out[longPreferencesKey("counter_keysetA")] = 10L } } + + val firstScope = CoroutineScope(Dispatchers.IO + SupervisorJob()) + DataStoreCashuCounterStore(raw(file, firstScope, listOf(migration()))).reserve("keysetA", 5) + firstScope.release() + + val secondScope = CoroutineScope(Dispatchers.IO + SupervisorJob()) + val reopened = DataStoreCashuCounterStore(raw(file, secondScope, listOf(migration()))) + assertEquals(15L, reopened.peek("keysetA")) + assertTrue("a later reservation is past everything spent", reopened.reserve("keysetA", 1) >= 15L) + secondScope.release() + } + + /** A host that wired no store must fail loudly rather than answer 0. */ + @Test + fun theUnavailableStoreRefusesToAnswer() = + runTest { + val onPeek = runCatching { UnavailableCashuKeysetCounterStore.peek("keyset1") }.exceptionOrNull() + val onReserve = runCatching { UnavailableCashuKeysetCounterStore.reserve("keyset1", 1) }.exceptionOrNull() + + assertTrue("peek must refuse, got $onPeek", onPeek is IllegalStateException) + assertTrue("reserve must refuse, got $onReserve", onReserve is IllegalStateException) + } +} diff --git a/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip60Cashu/mintApi/SecretFactory.kt b/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip60Cashu/mintApi/SecretFactory.kt index 51d662f82f..2da95e82fc 100644 --- a/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip60Cashu/mintApi/SecretFactory.kt +++ b/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip60Cashu/mintApi/SecretFactory.kt @@ -44,6 +44,18 @@ data class DerivedSecret( override fun hashCode(): Int = 31 * secretHex.hashCode() + blindingFactor.contentHashCode() } +/** + * Where a batch of deterministic secrets starts. + * + * [firstCounter] is null when the secrets will be random — either because the + * factory is [RandomSecretFactory], or because a [DeterministicSecretFactory] + * had no seed available when it reserved. + */ +data class SecretReservation( + val keysetId: String, + val firstCounter: Long?, +) + /** * Strategy for producing the (secret, r) pairs that go into BDHKE blind * messages. Two impls today: @@ -61,21 +73,48 @@ data class DerivedSecret( */ interface SecretFactory { /** - * Mint [count] (secret, r) pairs for use on the specified keyset. + * Reserve whatever durable state the next [count] secrets need, and return + * where they start. * - * Batched on purpose: the deterministic implementation reserves a - * contiguous counter range via a single atomic critical section on - * `AccountSettings.reserveCashuCounters`. Calling one-at-a-time - * inside `splitAmounts(amount).map { ... }` would take the lock N - * times per mint — wasteful for both contention and disk writes. + * Suspends because that is the durability boundary: a NUT-13 counter MUST + * reach disk before any secret derived from it reaches a mint, or a crash + * mid-mint replays the counter on the next launch and the mint answers + * `outputs already signed`. + * + * Separate from [derive] so that derivation stays pure and synchronous. + * Reserving is the only part that touches storage, and only a + * deterministic factory does so at all. */ - fun nextSecrets( + suspend fun reserve( keysetId: String, count: Int, + ): SecretReservation + + /** + * Derive [count] (secret, r) pairs from an already-reserved position. + * + * Pure: no storage, no suspension, same output for the same reservation. + */ + fun derive( + reservation: SecretReservation, + count: Int, ): List + /** + * Reserve and derive in one step. + * + * Batched on purpose: the deterministic implementation reserves a + * contiguous counter range in a single atomic write. Calling one-at-a-time + * inside `splitAmounts(amount).map { ... }` would take the lock N times per + * mint — wasteful for both contention and disk writes. + */ + suspend fun nextSecrets( + keysetId: String, + count: Int, + ): List = derive(reserve(keysetId, count), count) + /** Convenience for ops that need a single output. */ - fun nextSecret(keysetId: String): DerivedSecret = nextSecrets(keysetId, 1).first() + suspend fun nextSecret(keysetId: String): DerivedSecret = nextSecrets(keysetId, 1).first() } /** @@ -85,9 +124,15 @@ interface SecretFactory { * pre-dates the NUT-13 wiring). */ object RandomSecretFactory : SecretFactory { - override fun nextSecrets( + /** Nothing to reserve: random secrets keep no durable state. */ + override suspend fun reserve( keysetId: String, count: Int, + ): SecretReservation = SecretReservation(keysetId, null) + + override fun derive( + reservation: SecretReservation, + count: Int, ): List { require(count > 0) { "Must request at least one secret" } return List(count) { @@ -126,29 +171,51 @@ class DeterministicSecretFactory( private val seedProvider: () -> ByteArray?, /** * Atomically reserves [count] consecutive counters for a keyset and - * returns the FIRST one — the factory then derives at indices + * returns the FIRST one — derivation then runs at indices * `[returned .. returned+count)`. Persisting in one shot avoids the - * lock-N-times-per-mint waste of the old per-secret API. + * lock-N-times-per-mint waste of a per-secret API. * + * Suspends: it must reach disk before the secrets are used. * `AccountSettings.reserveCashuCounters(keysetId, count)` is the * canonical implementation. */ - private val reserveCounters: (keysetId: String, count: Int) -> Long, + private val reserveCounters: suspend (keysetId: String, count: Int) -> Long, private val fallback: SecretFactory = RandomSecretFactory, ) : SecretFactory { - override fun nextSecrets( + /** + * With no seed yet — the wallet has not decrypted its kind:17375 — this + * reserves nothing and reports a random batch, so counters are not burned + * for secrets that will not be derived from them. + */ + override suspend fun reserve( keysetId: String, count: Int, + ): SecretReservation { + require(count > 0) { "Must request at least one secret" } + seedProvider() ?: return SecretReservation(keysetId, null) + return SecretReservation(keysetId, reserveCounters(keysetId, count)) + } + + override fun derive( + reservation: SecretReservation, + count: Int, ): List { require(count > 0) { "Must request at least one secret" } - val seed = seedProvider() ?: return fallback.nextSecrets(keysetId, count) - val first = reserveCounters(keysetId, count) + val first = reservation.firstCounter ?: return fallback.derive(reservation, count) + + // Re-read rather than capturing the seed in the reservation, which + // would carry it through a public data class. If the seed vanished + // between reserving and deriving, this batch falls back to random and + // the reserved counters go unused — harmless, because counters only + // ever move forward and an unused one is never replayed. + val seed = seedProvider() ?: return fallback.derive(SecretReservation(reservation.keysetId, null), count) + return List(count) { offset -> val counter = first + offset // CashuDeterministic.secretBytes returns the raw 32 bytes; // the hex form is what BDHKE/proof storage actually use. - val secretHex = CashuDeterministic.secretBytes(seed, keysetId, counter).toHexKey() - val r = CashuDeterministic.blindingFactor(seed, keysetId, counter) + val secretHex = CashuDeterministic.secretBytes(seed, reservation.keysetId, counter).toHexKey() + val r = CashuDeterministic.blindingFactor(seed, reservation.keysetId, counter) DerivedSecret(secretHex, r) } } diff --git a/quartz/src/commonTest/kotlin/com/vitorpamplona/quartz/nip60Cashu/mintApi/SecretFactoryTest.kt b/quartz/src/commonTest/kotlin/com/vitorpamplona/quartz/nip60Cashu/mintApi/SecretFactoryTest.kt new file mode 100644 index 0000000000..1d6d88c318 --- /dev/null +++ b/quartz/src/commonTest/kotlin/com/vitorpamplona/quartz/nip60Cashu/mintApi/SecretFactoryTest.kt @@ -0,0 +1,150 @@ +/* + * Copyright (c) 2025 Vitor Pamplona + * + * Permission is hereby granted, free of charge, to any person obtaining a copy of + * this software and associated documentation files (the "Software"), to deal in + * the Software without restriction, including without limitation the rights to use, + * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the + * Software, and to permit persons to whom the Software is furnished to do so, + * subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in all + * copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS + * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR + * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN + * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + */ +package com.vitorpamplona.quartz.nip60Cashu.mintApi + +import kotlinx.coroutines.test.runTest +import kotlin.test.Test +import kotlin.test.assertEquals +import kotlin.test.assertNotEquals +import kotlin.test.assertNull +import kotlin.test.assertTrue + +/** + * The reserve/derive split. + * + * Reserving is the durability boundary — it suspends and must persist a NUT-13 + * counter before any secret derived from it reaches a mint. Deriving is pure. + * Keeping them apart is what lets [RandomSecretFactory] stay free of storage + * and lets the mint layer see where the write happens. + */ +class SecretFactoryTest { + private val seed = ByteArray(64) { it.toByte() } + + // Keyset ids are hex by NUT-02, and NUT-13 derivation decodes them, so a + // placeholder like "keyset1" is rejected before any secret is produced. + private val keysetA = "009a1f293253e41e" + private val keysetB = "00ad268c4d1f5826" + + @Test + fun randomFactoryReservesNothing() = + runTest { + val reservation = RandomSecretFactory.reserve(keysetA, 3) + + assertNull(reservation.firstCounter, "random secrets keep no durable state") + assertEquals(keysetA, reservation.keysetId) + } + + @Test + fun randomFactoryDerivesDistinctSecrets() = + runTest { + val secrets = RandomSecretFactory.nextSecrets(keysetA, 4) + + assertEquals(4, secrets.size) + assertEquals(4, secrets.map { it.secretHex }.toSet().size, "random secrets must not repeat") + } + + @Test + fun deterministicFactoryReservesTheWholeBatchOnce() = + runTest { + val calls = mutableListOf>() + val factory = + DeterministicSecretFactory( + seedProvider = { seed }, + reserveCounters = { keysetId, count -> + calls.add(keysetId to count) + 10L + }, + ) + + val reservation = factory.reserve(keysetA, 5) + + assertEquals(listOf(keysetA to 5), calls, "one reservation for the batch, not one per secret") + assertEquals(10L, reservation.firstCounter) + } + + /** + * With no seed the factory falls back to random, so reserving would burn + * counters for secrets that are never derived from them. + */ + @Test + fun noSeedMeansNoCountersBurned() = + runTest { + var reserved = false + val factory = + DeterministicSecretFactory( + seedProvider = { null }, + reserveCounters = { _, _ -> + reserved = true + 0L + }, + ) + + val reservation = factory.reserve(keysetA, 3) + + assertTrue(!reserved, "the counter store must not be touched") + assertNull(reservation.firstCounter) + } + + /** Derivation is pure: the same reservation yields the same secrets. */ + @Test + fun deriveIsDeterministicForAReservation() = + runTest { + val factory = DeterministicSecretFactory(seedProvider = { seed }, reserveCounters = { _, _ -> 7L }) + val reservation = SecretReservation(keysetA, 7L) + + assertEquals(factory.derive(reservation, 3), factory.derive(reservation, 3)) + } + + /** Consecutive counters must give different secrets, or a reused index would be harmless — it is not. */ + @Test + fun eachCounterInABatchDerivesADifferentSecret() = + runTest { + val factory = DeterministicSecretFactory(seedProvider = { seed }, reserveCounters = { _, _ -> 0L }) + + val secrets = factory.derive(SecretReservation(keysetA, 0L), 4) + + assertEquals(4, secrets.map { it.secretHex }.toSet().size) + } + + /** NUT-13 derivation is keyset-aware: the same counter on another keyset is a different secret. */ + @Test + fun theSameCounterOnAnotherKeysetDerivesADifferentSecret() = + runTest { + val factory = DeterministicSecretFactory(seedProvider = { seed }, reserveCounters = { _, _ -> 0L }) + + val onA = factory.derive(SecretReservation(keysetA, 0L), 1).first() + val onB = factory.derive(SecretReservation(keysetB, 0L), 1).first() + + assertNotEquals(onA.secretHex, onB.secretHex) + } + + /** A reservation carrying no counter derives random secrets, whatever the factory. */ + @Test + fun aCounterlessReservationFallsBackToRandom() = + runTest { + val factory = DeterministicSecretFactory(seedProvider = { seed }, reserveCounters = { _, _ -> 0L }) + + val first = factory.derive(SecretReservation(keysetA, null), 2) + val second = factory.derive(SecretReservation(keysetA, null), 2) + + assertNotEquals(first.map { it.secretHex }, second.map { it.secretHex }, "random, so not reproducible") + } +} diff --git a/quartz/src/jvmAndroid/kotlin/com/vitorpamplona/quartz/nip60Cashu/mintApi/CashuMintOperations.kt b/quartz/src/jvmAndroid/kotlin/com/vitorpamplona/quartz/nip60Cashu/mintApi/CashuMintOperations.kt index bedae4d049..024413a720 100644 --- a/quartz/src/jvmAndroid/kotlin/com/vitorpamplona/quartz/nip60Cashu/mintApi/CashuMintOperations.kt +++ b/quartz/src/jvmAndroid/kotlin/com/vitorpamplona/quartz/nip60Cashu/mintApi/CashuMintOperations.kt @@ -723,7 +723,7 @@ class CashuMintOperations( */ private suspend fun fetchInputFeePpkByKeyset(): Map = client.keysets().keysets.associate { it.id to (it.inputFeePpk ?: 0L) } - private fun createBlindedOutputs( + private suspend fun createBlindedOutputs( amount: Long, keyset: KeysetDto, ): List = secretOutputsFor(splitAmounts(amount), keyset) @@ -735,7 +735,7 @@ class CashuMintOperations( * [SecretFactory.nextSecret] per amount instead would take the * @Synchronized lock + dirty `AccountSettings.saveable` N times. */ - private fun secretOutputsFor( + private suspend fun secretOutputsFor( amounts: List, keyset: KeysetDto, ): List { @@ -744,7 +744,12 @@ class CashuMintOperations( // [secretFactory] decides whether those bytes are pure-random or // NUT-13-derived from a wallet seed; either way the on-wire shape // is identical so the mint can't tell which scheme we're using. - val derived = secretFactory.nextSecrets(keyset.id, amounts.size) + // Two steps on purpose. reserve() suspends and persists the NUT-13 + // counter; derive() is pure. Keeping them apart means the durability + // boundary is visible here, at the only layer that can await it, rather + // than hidden inside secret derivation. + val reservation = secretFactory.reserve(keyset.id, amounts.size) + val derived = secretFactory.derive(reservation, amounts.size) return amounts.mapIndexed { i, amount -> val pair = derived[i] val bTick = Bdhke.blind(pair.secretHex.encodeToByteArray(), pair.blindingFactor)