feat: add spark via breez sdk

.github/workflows/release-internal.yml

@@ -73,6 +73,8 @@ jobs:
           KEYSTORE_PASSWORD: ${{ secrets.INTERNAL_KEYSTORE_PASSWORD }}
           KEY_ALIAS: ${{ secrets.INTERNAL_KEY_ALIAS }}
           KEY_PASSWORD: ${{ secrets.INTERNAL_KEY_PASSWORD }}
+          # Optional: without it the build passes and Spark (Lightning without channels) stays off.
+          BREEZ_API_KEY: ${{ secrets.BREEZ_API_KEY }}
         run: |
           set -euo pipefail
           ./gradlew assembleMainnetRelease --no-daemon --stacktrace

.github/workflows/release.yml

@@ -66,6 +66,15 @@ jobs:
           printf '%s' "$BITKIT_KEYSTORE_BASE64" | base64 --decode > "$keystore_path"
           echo "KEYSTORE_FILE=$keystore_path" >> "$GITHUB_ENV"
 
+      - name: Check Breez API key
+        env:
+          BREEZ_API_KEY: ${{ secrets.BREEZ_API_KEY }}
+        run: |
+          if [ -z "${BREEZ_API_KEY// /}" ]; then
+            echo "::error::BREEZ_API_KEY is missing from the release environment; a release without it ships with Spark (Lightning without channels) off."
+            exit 1
+          fi
+
       - name: Build release artifacts
         env:
           GPR_USER: ${{ secrets.GPR_USER || github.actor }}
@@ -74,6 +83,7 @@ jobs:
           KEYSTORE_PASSWORD: ${{ secrets.BITKIT_KEYSTORE_PASSWORD }}
           KEY_ALIAS: ${{ secrets.BITKIT_KEY_ALIAS }}
           KEY_PASSWORD: ${{ secrets.BITKIT_KEY_PASSWORD }}
+          BREEZ_API_KEY: ${{ secrets.BREEZ_API_KEY }}
         run: |
           set -euo pipefail
           ./gradlew assembleMainnetRelease bundleMainnetRelease --no-daemon --stacktrace

app/build.gradle.kts

@@ -356,6 +356,8 @@ androidComponents {
             "USDT_RPC_URL",
             localProp("USDT_RPC_URL").orElse("https://bitkit.to/v1/usdt/chain-rpc").stringField(),
         )
+        buildConfigFields.put("BREEZ_API_KEY", localProp("BREEZ_API_KEY").orElse("").stringField())
+        buildConfigFields.put("ESPLORA_URL", localProp("ESPLORA_URL").orElse("").stringField())
         buildConfigFields.put("E2E", e2eEnv.booleanField())
         buildConfigFields.put("E2E_BACKEND", e2eBackendEnv.stringField())
         buildConfigFields.put("E2E_LOCAL_HOST", e2eLocalHostEnv.stringField())
@@ -566,6 +568,7 @@ dependencies {
         implementation(libs.bitkit.core)
     }
     implementation(libs.paykit)
+    implementation(libs.breez.sdk.spark) { exclude(group = "net.java.dev.jna", module = "jna") }
     implementation(libs.vss.client)
     if (localBitkitCoreAar == null) nativeDebugSymbols(libs.bitkit.core.nativeDebugSymbolsArtifact())
     nativeDebugSymbols(libs.ldk.node.android.nativeDebugSymbolsArtifact())

app/src/main/java/to/bitkit/data/CacheStore.kt

@@ -21,6 +21,22 @@ import to.bitkit.models.WalletScope
 import to.bitkit.utils.Logger
 import javax.inject.Inject
 import javax.inject.Singleton
+import kotlin.time.Clock
+
+/**
+ * A listing drops a rail's send hashes it shows failed only, or paid once the invoice has expired, so the other rail
+ * cannot pay it again, and ones it doesn't show once the invoice expired [UNLISTED_SEND_SETTLE_SECS] ago. Paid or
+ * unlisted sends with no known expiry (kept before expiries were, or whose invoice can't be parsed) are dropped oldest
+ * first only past this many hashes. A send that may be pending always stays.
+ */
+internal const val MAX_SPARK_SEND_HASHES = 100
+
+/**
+ * How long past its invoice's expiry a send no listing shows may still be pending: no send starts after the expiry,
+ * and one settles within its HTLC timeout, which LDK caps at 1008 blocks (about a week) and Spark's routes keep
+ * shorter, so twice that cap leaves room for slow blocks.
+ */
+internal const val UNLISTED_SEND_SETTLE_SECS = 14L * 24 * 60 * 60
 
 private val Context.appCacheDataStore: DataStore<AppCacheData> by dataStore(
     fileName = "app_cache.json",
@@ -30,6 +46,7 @@ private val Context.appCacheDataStore: DataStore<AppCacheData> by dataStore(
 @Singleton
 class CacheStore internal constructor(
     private val store: DataStore<AppCacheData>,
+    private val clock: Clock = Clock.System,
 ) {
     @Inject
     constructor(@ApplicationContext context: Context) : this(context.appCacheDataStore)
@@ -136,6 +153,125 @@ class CacheStore internal constructor(
         store.updateData { it.copy(pendingLightningMessages = it.pendingLightningMessages - paymentHash) }
     }
 
+    /** Keeps [paymentHash] with its invoice's expiry in epoch seconds, [expiresAt], when known. */
+    suspend fun addSparkSendHash(paymentHash: String, expiresAt: Long? = null) {
+        val hash = paymentHash.lowercase()
+        store.updateData {
+            it.copy(
+                sparkSendHashes = it.sparkSendHashes - hash + hash,
+                sparkSendExpiries = it.sparkSendExpiries.with(hash, expiresAt),
+            )
+        }
+    }
+
+    suspend fun removeSparkSendHash(paymentHash: String) {
+        val hash = paymentHash.lowercase()
+        if (hash !in store.data.first().sparkSendHashes) return
+        store.updateData {
+            it.copy(sparkSendHashes = it.sparkSendHashes - hash, sparkSendExpiries = it.sparkSendExpiries - hash)
+        }
+    }
+
+    /** Keeps Spark's send of [paymentHash] as one whose outcome Spark didn't report, since [failedAt] epoch seconds. */
+    suspend fun addSparkUncertainSend(paymentHash: String, failedAt: Long) {
+        val hash = paymentHash.lowercase()
+        store.updateData { it.copy(sparkUncertainSends = it.sparkUncertainSends + (hash to failedAt)) }
+    }
+
+    suspend fun removeSparkUncertainSend(paymentHash: String) {
+        val hash = paymentHash.lowercase()
+        if (hash !in store.data.first().sparkUncertainSends) return
+        store.updateData { it.copy(sparkUncertainSends = it.sparkUncertainSends - hash) }
+    }
+
+    /** Keeps [paymentHash] with its invoice's expiry in epoch seconds, [expiresAt], when known. */
+    suspend fun addLdkSendHash(paymentHash: String, expiresAt: Long? = null) {
+        val hash = paymentHash.lowercase()
+        store.updateData {
+            it.copy(
+                ldkSendHashes = it.ldkSendHashes - hash + hash,
+                ldkSendExpiries = it.ldkSendExpiries.with(hash, expiresAt),
+            )
+        }
+    }
+
+    private fun Map<String, Long>.with(hash: String, expiresAt: Long?) =
+        if (expiresAt == null) this else this + (hash to expiresAt)
+
+    /** Keeps [paymentHashes], the node's pending and paid sends, once, ahead of the hashes kept since. */
+    suspend fun seedLdkSendHashes(paymentHashes: List<String>) {
+        if (store.data.first().ldkSendHashesSeeded) return
+        store.updateData { data ->
+            if (data.ldkSendHashesSeeded) return@updateData data
+            val seeded = paymentHashes.map { it.lowercase() }.distinct() - data.ldkSendHashes.toSet()
+            data.copy(
+                ldkSendHashes = seeded + data.ldkSendHashes,
+                ldkSendHashesSeeded = true,
+            )
+        }
+    }
+
+    /**
+     * Drops the node's sends a listing showed as [failed] only, or as [paid] with an expired invoice, ones it didn't
+     * show ([listed] is every hash it shows) whose invoice expired past [UNLISTED_SEND_SETTLE_SECS], and past the cap
+     * the oldest paid or unlisted ones with no known expiry. A send that may be pending ([live]) always stays.
+     */
+    suspend fun trimLdkSendHashes(paid: Set<String>, failed: Set<String>, listed: Set<String>, live: Set<String>) {
+        store.updateData {
+            val (hashes, expiries) =
+                withoutSettled(it.ldkSendHashes, it.ldkSendExpiries, SendListing(paid, failed, listed, live))
+            it.copy(ldkSendHashes = hashes, ldkSendExpiries = expiries)
+        }
+    }
+
+    /** Drops Spark's sends as [trimLdkSendHashes] drops the node's. */
+    suspend fun trimSparkSendHashes(paid: Set<String>, failed: Set<String>, listed: Set<String>, live: Set<String>) {
+        store.updateData {
+            val (hashes, expiries) =
+                withoutSettled(it.sparkSendHashes, it.sparkSendExpiries, SendListing(paid, failed, listed, live))
+            it.copy(sparkSendHashes = hashes, sparkSendExpiries = expiries)
+        }
+    }
+
+    private class SendListing(paid: Set<String>, failed: Set<String>, listed: Set<String>, live: Set<String>) {
+        val paid = paid.lowercased()
+        val failed = failed.lowercased()
+        val listed = listed.lowercased()
+        val live = live.lowercased()
+
+        private fun Set<String>.lowercased() = mapTo(mutableSetOf()) { it.lowercase() }
+    }
+
+    private fun withoutSettled(
+        hashes: List<String>,
+        expiries: Map<String, Long>,
+        listing: SendListing,
+    ): Pair<List<String>, Map<String, Long>> {
+        val now = clock.now().epochSeconds
+
+        // Compared against now minus the window, as an invoice that never expires is kept at Long.MAX_VALUE.
+        fun isExpired(hash: String, settleSecs: Long = 0) = expiries[hash]?.let { it <= now - settleSecs } == true
+        fun isSettled(hash: String) = hash !in listing.live && (
+            hash in listing.failed ||
+                hash in listing.paid && isExpired(hash) ||
+                hash !in listing.listed && isExpired(hash, UNLISTED_SEND_SETTLE_SECS)
+            )
+        fun isAged(hash: String) =
+            hash !in listing.live && hash !in expiries && (hash in listing.paid || hash !in listing.listed)
+        val unsettled = hashes.filterNot(::isSettled)
+        var excess = unsettled.size - MAX_SPARK_SEND_HASHES
+        val kept = unsettled.filterNot { hash -> (excess > 0 && isAged(hash)).also { if (it) excess-- } }
+        return kept to expiries.filterKeys { it in kept }
+    }
+
+    suspend fun removeLdkSendHash(paymentHash: String) {
+        val hash = paymentHash.lowercase()
+        if (hash !in store.data.first().ldkSendHashes) return
+        store.updateData {
+            it.copy(ldkSendHashes = it.ldkSendHashes - hash, ldkSendExpiries = it.ldkSendExpiries - hash)
+        }
+    }
+
     suspend fun setBackgroundReceive(details: NewTransactionSheetDetails) = store.updateData {
         it.copy(backgroundReceive = details)
     }
@@ -169,6 +305,24 @@ data class AppCacheData(
     val quickPayLedger: QuickPayLedger? = null,
     /** LNURL-pay comments by payment hash, kept until the sent payment's activity stores them. */
     val pendingLightningMessages: Map<String, String> = mapOf(),
+    /** Hashes of the latest Lightning sends Spark started, so the node holds off while Spark can't list them. */
+    val sparkSendHashes: List<String> = listOf(),
+    /** Invoice expiry in epoch seconds of the [sparkSendHashes] that know it. */
+    val sparkSendExpiries: Map<String, Long> = mapOf(),
+    /**
+     * Spark's sends whose outcome it didn't report, by hash, with when they failed in epoch seconds, so a restart
+     * never reads a retry's earlier failed attempt as its outcome.
+     */
+    val sparkUncertainSends: Map<String, Long> = mapOf(),
+    /** Hashes of the Lightning sends the node started, so Spark holds off while the node can't list them. */
+    val ldkSendHashes: List<String> = listOf(),
+    /** Invoice expiry in epoch seconds of the [ldkSendHashes] that know it. */
+    val ldkSendExpiries: Map<String, Long> = mapOf(),
+    /**
+     * Set once the node's own list has filled [ldkSendHashes], as node sends made before hashes were kept carry none
+     * there. Until then an unlistable node holds every Spark send.
+     */
+    val ldkSendHashesSeeded: Boolean = false,
 ) {
     fun isContactDetached(activityId: String, walletId: String): Boolean =
         scopedActivityId(walletId, activityId) in detachedActivityContacts

app/src/main/java/to/bitkit/data/SettingsStore.kt

@@ -212,7 +212,9 @@ data class SettingsData(
     val selectedCurrency: String = "USD",
     val defaultTransactionSpeed: TransactionSpeed = TransactionSpeed.default(),
     val showEmptyBalanceView: Boolean = true,
+    val hasSeenSpendingIntro: Boolean = false,
     val hasSeenWidgetsIntro: Boolean = false,
+    val hasSeenTransferIntro: Boolean = false,
     val hasSeenSavingsIntro: Boolean = false,
     val hasSeenShopIntro: Boolean = false,
     val hasSeenProfileIntro: Boolean = false,

app/src/main/java/to/bitkit/di/RepoModule.kt

@@ -12,7 +12,9 @@ import to.bitkit.repositories.LightningRepo
 import to.bitkit.repositories.QuickPayInvoiceParser
 import to.bitkit.repositories.QuickPayPaymentLookup
 import to.bitkit.repositories.QuickPayReconcileRow
+import to.bitkit.repositories.SparkRepo
 import javax.inject.Named
+import breez_sdk_spark.PaymentStatus as SparkPaymentStatus
 
 @Module
 @InstallIn(SingletonComponent::class)
@@ -33,8 +35,39 @@ abstract class RepoModule {
             runCatching { Bolt11Invoice.fromStr(bolt11).paymentHash() }.getOrNull()
         }
 
+        /**
+         * Payments of both rails, one row per invoice for a payment either rail made, so an older failed channel
+         * attempt never settles one a Spark retry still holds or paid. Null while either rail can't list them.
+         */
         @Provides
-        fun provideQuickPayPaymentLookup(lightningRepo: LightningRepo): QuickPayPaymentLookup =
-            QuickPayPaymentLookup { lightningRepo.listPaymentsOrNull()?.map { QuickPayReconcileRow(it) } }
+        fun provideQuickPayPaymentLookup(lightningRepo: LightningRepo, sparkRepo: SparkRepo): QuickPayPaymentLookup =
+            QuickPayPaymentLookup {
+                val node = lightningRepo.listPaymentsOrNull()?.map { QuickPayReconcileRow(it) }
+                    ?: return@QuickPayPaymentLookup null
+                val spark = sparkRepo.lightningSendStatuses() ?: return@QuickPayPaymentLookup null
+                val sparkRows = spark.map { (hash, status) ->
+                    QuickPayReconcileRow(
+                        paymentId = hash,
+                        invoicePaymentHash = hash,
+                        isOutboundBolt11 = true,
+                        status = when (status) {
+                            SparkPaymentStatus.COMPLETED -> QuickPayReconcileRow.Status.SUCCEEDED
+                            SparkPaymentStatus.PENDING -> QuickPayReconcileRow.Status.PENDING
+                            SparkPaymentStatus.FAILED -> QuickPayReconcileRow.Status.FAILED
+                        },
+                    )
+                }
+                val (sends, others) = (node + sparkRows).partition { it.isOutboundBolt11 }
+                others + sends.groupBy { it.invoicePaymentHash }.values.map { rows ->
+                    rows.maxBy { SETTLING_STATUSES.indexOf(it.status) }
+                }
+            }
+
+        /** The order in which an outcome settles a payment both rails attempted, the last one winning. */
+        private val SETTLING_STATUSES = listOf(
+            QuickPayReconcileRow.Status.FAILED,
+            QuickPayReconcileRow.Status.PENDING,
+            QuickPayReconcileRow.Status.SUCCEEDED,
+        )
     }
 }

app/src/main/java/to/bitkit/domain/commands/NotifyPaymentReceivedHandler.kt

@@ -15,6 +15,7 @@ import to.bitkit.models.NewTransactionSheetType
 import to.bitkit.models.msatCeilOf
 import to.bitkit.repositories.ActivityRepo
 import to.bitkit.repositories.BackupRepo
+import to.bitkit.repositories.SparkRepo
 import to.bitkit.services.MigrationService
 import to.bitkit.utils.Logger
 import javax.inject.Inject
@@ -35,6 +36,7 @@ class NotifyPaymentReceivedHandler @Inject constructor(
     private val settingsStore: SettingsStore,
     private val clock: Clock,
     private val receivedNotificationContent: ReceivedNotificationContent,
+    private val sparkRepo: SparkRepo,
 ) {
     private val presentationClaimsLock = Any()
     private val presentationClaims = mutableSetOf<String>()
@@ -124,6 +126,11 @@ class NotifyPaymentReceivedHandler @Inject constructor(
             if (command.details.amountSats <= 0) return false
         }
 
+        if (sparkRepo.markWithdrawalAsTransfer(command.txid)) {
+            Logger.debug("Skipping onchain receive '${command.txid}' from a Spark withdrawal", context = TAG)
+            return false
+        }
+
         if (settings.pendingRestoreActivitySeen) {
             Logger.debug("Skipping onchain receive '${command.txid}' until the first sync after restore", context = TAG)
             return false

app/src/main/java/to/bitkit/env/Env.kt

@@ -31,6 +31,15 @@ internal object Env {
         ).filter { it.first in enabled }.map { it.second }
     }
 
+    val breezApiKey: String? get() = BuildConfig.BREEZ_API_KEY.takeIf { it.isNotBlank() }
+
+    /**
+     * Esplora endpoint for the node's chain source on regtest builds, set to put the wallet on Spark's regtest chain
+     * through `scripts/spark-regtest-esplora.py`; Electrum is used when unset.
+     */
+    val regtestEsploraUrl: String?
+        get() = BuildConfig.ESPLORA_URL.takeIf { it.isNotBlank() && network == Network.REGTEST }
+
     val isDebug = BuildConfig.DEBUG
     const val isE2eTest = BuildConfig.E2E
     val e2eBackend = BuildConfig.E2E_BACKEND.lowercase()
@@ -120,6 +129,22 @@ internal object Env {
             Network.REGTEST -> "https://mempool.bitkit.stag0.blocktank.to/"
         }
 
+    /**
+     * Whether the node's chain is the one Spark watches, so an on-chain funding of Spark from Savings or a hardware
+     * wallet reaches it. On regtest Spark runs on Lightspark's own chain, which the node joins only through the
+     * Spark regtest Esplora proxy.
+     */
+    fun sparkSharesNodeChain(network: Network, regtestEsploraUrl: String?): Boolean =
+        network != Network.REGTEST || regtestEsploraUrl != null
+
+    val sparkSharesNodeChain: Boolean get() = sparkSharesNodeChain(network, regtestEsploraUrl)
+
+    /** Esplora REST that Spark reads the chain from; null keeps the SDK's default, on staging and regtest. */
+    fun sparkChainServiceUrl(network: Network): String? = when (network) {
+        Network.BITCOIN -> bitkitEsploraUrl
+        else -> null
+    }
+
     val blocktankBaseUrl
         get() = when (network) {
             Network.BITCOIN -> "https://api1.blocktank.to"
@@ -143,6 +168,7 @@ internal object Env {
     const val chatwootUrl = "https://synonym.to/api/chatwoot"
     const val newsBaseUrl = "https://feeds.synonym.to/news-feed/api"
     const val mempoolBaseUrl = "https://mempool.space/api"
+    const val bitkitEsploraUrl = "https://bitkit.to/electrs"
     const val pricesWidgetBaseUrl = "https://feeds.synonym.to/price-feed/api"
 
     const val APP_STORE_URL = "https://apps.apple.com/app/bitkit-wallet/id6502440655"
@@ -226,6 +252,12 @@ internal object Env {
 
     fun ldkStoragePath(walletIndex: Int) = storagePathOf(walletIndex, network.name.lowercase(), "ldk")
 
+    fun sparkStoragePath(walletIndex: Int) = storagePathOf(walletIndex, network.name.lowercase(), "spark")
+
+    /** A restored Spark exit data backup waiting to be imported once Spark connects; outside Spark's storage. */
+    fun sparkExitRestorePath(walletIndex: Int) =
+        Path(storagePathOf(walletIndex, network.name.lowercase(), "spark-restore"), "exit-state.json").toString()
+
     fun bitkitCoreStoragePath(walletIndex: Int): String {
         return storagePathOf(walletIndex, network.name.lowercase(), "core")
     }