feat: pay contacts via spark

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

@@ -18,6 +18,8 @@ import to.bitkit.models.FxRate
 import to.bitkit.models.NewTransactionSheetDetails
 import to.bitkit.models.QuickPayLedger
 import to.bitkit.models.WalletScope
+import to.bitkit.repositories.PendingSparkWithdrawal
+import to.bitkit.repositories.SentSparkWithdrawal
 import to.bitkit.utils.Logger
 import javax.inject.Inject
 import javax.inject.Singleton
@@ -334,6 +336,10 @@ 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(),
+    /** A Spark withdrawal to a Paykit contact that started, kept until Spark's payment list settles it. */
+    val pendingSparkWithdrawal: PendingSparkWithdrawal? = null,
+    /** The latest Spark withdrawals to Paykit contacts that settled as sent, so a restart never reads one as unsent. */
+    val sentSparkWithdrawals: List<SentSparkWithdrawal> = listOf(),
     /** 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. */

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

@@ -0,0 +1,54 @@
+package to.bitkit.data
+
+import io.ktor.client.HttpClient
+import io.ktor.client.request.get
+import io.ktor.client.statement.bodyAsText
+import io.ktor.http.HttpStatusCode
+import io.ktor.http.isSuccess
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.boolean
+import kotlinx.serialization.json.jsonObject
+import kotlinx.serialization.json.jsonPrimitive
+import org.lightningdevkit.ldknode.Network
+import to.bitkit.env.Env
+import to.bitkit.ext.runSuspendCatching
+import to.bitkit.utils.Logger
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Whether a Spark withdrawal's payout transaction is mined, asked of the Esplora chain Spark reads. Unlike the payout
+ * address's unspent outputs, the transaction's status still answers once the contact has spent the payout.
+ */
+@Singleton
+class SparkPayoutChain @Inject constructor(
+    private val client: HttpClient,
+) {
+    companion object {
+        private const val TAG = "SparkPayoutChain"
+        private const val SPARK_REGTEST_ESPLORA_URL = "https://regtest-mempool.us-west-2.sparkinfra.net/api"
+        private val json = Json { ignoreUnknownKeys = true }
+
+        /** The Esplora to ask on [network]: the one Spark reads there, or null where the app knows none. */
+        fun esploraUrl(network: Network): String? = when (network) {
+            Network.BITCOIN -> Env.bitkitEsploraUrl
+            Network.REGTEST -> SPARK_REGTEST_ESPLORA_URL
+            else -> null
+        }
+    }
+
+    /** Whether [txid] is in a block; null when this network has no Esplora to ask or the lookup failed. */
+    suspend fun isMined(txid: String): Boolean? {
+        val baseUrl = esploraUrl(Env.network) ?: return null
+        return runSuspendCatching {
+            val response = client.get("$baseUrl/tx/$txid/status")
+            // Spark can list a payout before it is broadcast, and the chain then knows no such transaction yet.
+            if (response.status == HttpStatusCode.NotFound) return@runSuspendCatching false
+            check(response.status.isSuccess()) { "status ${response.status.value}" }
+            json.parseToJsonElement(response.bodyAsText()).jsonObject.getValue("confirmed").jsonPrimitive.boolean
+        }.getOrElse {
+            Logger.warn("Failed to look up Spark payout transaction '$txid'", it, context = TAG)
+            null
+        }
+    }
+}

app/src/main/java/to/bitkit/models/PaykitPaymentStateBackup.kt

@@ -66,6 +66,7 @@ data class PaykitPaymentStateBackup(
         val privatePaymentListVersion: ULong? = null,
         val previousPrivatePaymentListVersion: ULong? = null,
         val allowanceId: String? = null,
+        val sparkWithdrawal: Boolean = false,
     ) {
         init {
             require(
@@ -98,6 +99,7 @@ data class PaykitPaymentStateBackup(
             privatePaymentListVersion = proof.privatePaymentListVersion,
             previousPrivatePaymentListVersion = proof.previousPrivatePaymentListVersion,
             allowanceId = proof.allowanceId,
+            sparkWithdrawal = proof.sparkWithdrawal,
         )
 
         fun restored() = PendingPaykitPaymentProof(
@@ -124,6 +126,7 @@ data class PaykitPaymentStateBackup(
             privatePaymentListVersion = privatePaymentListVersion,
             previousPrivatePaymentListVersion = previousPrivatePaymentListVersion,
             allowanceId = allowanceId,
+            sparkWithdrawal = sparkWithdrawal,
         )
     }
 }

app/src/main/java/to/bitkit/repositories/LightningRepo.kt

@@ -153,6 +153,9 @@ class LightningRepo @Inject constructor(
     /** Whether Spark synced its payments since it connected, so its payment list is complete. */
     val isSparkSynced: Flow<Boolean> get() = sparkRepo.state.map { it.hasSynced }.distinctUntilChanged()
 
+    /** How each journaled Spark contact withdrawal closed. */
+    val sparkWithdrawalSettlements: Flow<SparkWithdrawalSettlement> get() = sparkRepo.withdrawalSettlements
+
     private val scope = appScope(bgDispatcher, TAG)
 
     private val _eventHandlers = ConcurrentHashMap.newKeySet<NodeEventHandler>()
@@ -2610,9 +2613,22 @@ class LightningRepo @Inject constructor(
         }
     }
 
+    /** What became of a Spark withdrawal attempt of exactly [amountSats] to [address], from Spark's payment list. */
+    suspend fun sparkWithdrawalOutcome(
+        address: String,
+        amountSats: ULong,
+        earlierTxids: Set<String>,
+    ): SparkWithdrawalOutcome = sparkRepo.withdrawalOutcome(address, amountSats, earlierTxids)
+
+    /** Txids of the Spark withdrawals to [address] so far, which a new attempt to it never counts as its own. */
+    suspend fun sparkWithdrawalTxidsTo(address: String): Set<String> = sparkRepo.withdrawalTxidsTo(address)
+
     /** Whether Spark alone can pay [amountSats], which it does whenever the node cannot. */
     fun canSendWithSpark(amountSats: ULong): Boolean = sparkRepo.canSend(amountSats)
 
+    /** Whether Spark's whole balance covers a withdrawal debiting [debitSats], its fees included. */
+    fun canWithdrawWithSpark(debitSats: ULong): Boolean = sparkRepo.canWithdraw(debitSats)
+
     fun canSend(amountSats: ULong): Boolean {
         val state = _lightningState.value
         if (sparkRepo.canSend(amountSats)) return true

app/src/main/java/to/bitkit/repositories/PaykitAllowanceExecutor.kt

@@ -1113,6 +1113,27 @@ class PaykitAllowanceExecutor @Inject constructor(
         }
     }
 
+    /**
+     * Records a manual on-chain send of [requestId] that Spark's list later shows sent as succeeded with its
+     * [transactionId], so an attempt left unknown no longer holds the request. Throws when an outcome could not be
+     * recorded, so the proof that found it stays for another pass.
+     */
+    suspend fun onchainSendSettled(payerIdentity: String?, requestId: PaykitPaymentRequestId, transactionId: String) {
+        val identity = activeIdentity?.takeIf { PubkyPublicKeyFormat.matches(it, payerIdentity) } ?: return
+        withContext(ioDispatcher) {
+            settleMutex.withLock {
+                val attempts = localState(identity).journal.filter {
+                    it.requestId == requestId && !it.isAutomatic && it.paymentHash == null &&
+                        it.stage in SETTLEABLE_STAGES
+                }
+                for (attempt in attempts) {
+                    updateJournalEntry(attempt.attemptId, identity) { it.copy(transactionId = transactionId) }
+                    record(attempt.attemptId, PaymentOutcome.SUCCEEDED, identity)
+                }
+            }
+        }
+    }
+
     // endregion
 
     // region Helpers

app/src/main/java/to/bitkit/repositories/PaykitPaymentProofRepo.kt

@@ -110,6 +110,8 @@ data class PendingPaykitPaymentProof(
     val previousPrivatePaymentListVersion: ULong? = null,
     /** Set only for an automatic Allowance payment, from its submitted attempt. Manual payments omit it. */
     val allowanceId: String? = null,
+    /** An on-chain payment sent as a Spark withdrawal, settled from Spark's payment list instead of the node's. */
+    val sparkWithdrawal: Boolean = false,
 )
 
 data class PaykitOnchainPaymentProofResolution(
@@ -120,6 +122,12 @@ data class PaykitOnchainPaymentProofResolution(
     val amountSats: ULong? = null,
 )
 
+/** A request whose uncertain Spark withdrawal Spark showed never sent, so its pending payment can fail. */
+data class PaykitSparkWithdrawalRelease(
+    val identity: String,
+    val requestId: PaykitPaymentRequestId,
+)
+
 @Singleton
 class PaykitPaymentProofRepo @Inject constructor(
     @IoDispatcher private val ioDispatcher: CoroutineDispatcher,
@@ -186,6 +194,8 @@ class PaykitPaymentProofRepo @Inject constructor(
     }
     private val _onchainPaymentResolutions = MutableStateFlow<List<PaykitOnchainPaymentProofResolution>>(emptyList())
     val onchainPaymentResolutions = _onchainPaymentResolutions.asStateFlow()
+    private val _sparkWithdrawalReleases = MutableStateFlow<List<PaykitSparkWithdrawalRelease>>(emptyList())
+    val sparkWithdrawalReleases = _sparkWithdrawalReleases.asStateFlow()
 
     suspend fun prepare(
         request: PaykitPaymentRequest,
@@ -308,6 +318,48 @@ class PaykitPaymentProofRepo @Inject constructor(
         privatePaymentListVersion: ULong? = null,
         signedTx: HwFundingSignedTx? = null,
         previousPrivatePaymentListVersion: ULong? = null,
+    ): Result<Unit> = markOnchainStarted(
+        request = request,
+        address = address,
+        amountSats = amountSats,
+        walletId = walletId,
+        privatePaymentListVersion = privatePaymentListVersion,
+        signedTx = signedTx,
+        previousPrivatePaymentListVersion = previousPrivatePaymentListVersion,
+        sparkWithdrawal = false,
+    )
+
+    /** Marks the on-chain proof of [request] started for a Spark withdrawal of [amountSats] to [address]. */
+    suspend fun markSparkOnchainPaymentStarted(
+        request: PaykitPaymentRequest,
+        address: String,
+        amountSats: ULong,
+        privatePaymentListVersion: ULong? = null,
+        previousPrivatePaymentListVersion: ULong? = null,
+        earlierWithdrawalTxids: Set<String> = emptySet(),
+    ): Result<Unit> = markOnchainStarted(
+        request = request,
+        address = address,
+        amountSats = amountSats,
+        walletId = WalletScope.default,
+        privatePaymentListVersion = privatePaymentListVersion,
+        signedTx = null,
+        previousPrivatePaymentListVersion = previousPrivatePaymentListVersion,
+        sparkWithdrawal = true,
+        earlierWithdrawalTxids = earlierWithdrawalTxids,
+    )
+
+    @Suppress("LongParameterList")
+    private suspend fun markOnchainStarted(
+        request: PaykitPaymentRequest,
+        address: String,
+        amountSats: ULong,
+        walletId: String,
+        privatePaymentListVersion: ULong?,
+        signedTx: HwFundingSignedTx?,
+        previousPrivatePaymentListVersion: ULong?,
+        sparkWithdrawal: Boolean,
+        earlierWithdrawalTxids: Set<String> = emptySet(),
     ): Result<Unit> = withContext(ioDispatcher) {
         runSuspendCatching {
             val identity = currentIdentity() ?: throw PaykitPaymentRequestError.RequestUnavailable
@@ -347,12 +399,124 @@ class PaykitPaymentProofRepo @Inject constructor(
                     hardwareFeeRate = signedTx?.feeRate,
                     hardwareTotalSpent = signedTx?.totalSpent,
                     hardwareDispatchAttempted = signedTx?.let { false },
+                    sparkWithdrawal = sparkWithdrawal,
+                    onchainMatchingTransactionIdsBeforeAttempt = if (sparkWithdrawal) {
+                        earlierWithdrawalTxids
+                    } else {
+                        proofs[index].onchainMatchingTransactionIdsBeforeAttempt
+                    },
                 )
                 persist(proofs)
             }
         }.onFailure { Logger.warn("Failed to mark a Paykit on-chain payment as started", it, context = TAG) }
     }
 
+    /** Completes the started proof of [request] paid by the Spark withdrawal [txid] and delivers it. */
+    suspend fun completeSparkOnchainPayment(request: PaykitPaymentRequest, txid: String): Boolean =
+        withContext(ioDispatcher) {
+            if (!txid.isHex(HASH_BYTE_COUNT)) return@withContext false
+            val identity = currentIdentity() ?: return@withContext false
+            runSuspendCatching {
+                operationMutex.withLock {
+                    val proof = loadProofs().lastOrNull {
+                        PubkyPublicKeyFormat.matches(it.identity, identity) && it.requestId == request.id &&
+                            it.sparkWithdrawal && it.paymentStarted && it.proofData == null
+                    } ?: return@withLock false
+                    completeSparkOnchainProofLocked(proof, txid)
+                }
+            }.onFailure {
+                Logger.warn("Failed to complete a Paykit proof for a Spark withdrawal", it, context = TAG)
+            }.getOrDefault(false)
+        }
+
+    /**
+     * Releases the started Spark proof of [request] when Spark shows its withdrawal never sent, so the request can be
+     * paid again; returns whether it did.
+     */
+    suspend fun releaseUnsentSparkOnchainProof(request: PaykitPaymentRequest): Boolean = withContext(ioDispatcher) {
+        val identity = currentIdentity() ?: return@withContext false
+        runSuspendCatching {
+            operationMutex.withLock {
+                val proof = loadProofs().lastOrNull {
+                    PubkyPublicKeyFormat.matches(it.identity, identity) && it.requestId == request.id &&
+                        it.sparkWithdrawal && it.paymentStarted && it.proofData == null
+                } ?: return@withLock false
+                reconcileSparkOnchainProof(proof)
+                loadProofs().none { it == proof }
+            }
+        }.onFailure {
+            Logger.warn("Failed to release an unsent Spark withdrawal proof", it, context = TAG)
+        }.getOrDefault(false)
+    }
+
+    /**
+     * Releases the started Spark proof of [request] for a withdrawal Spark refused before its journal was written, so
+     * nothing left the wallet and no listing is needed; returns whether it did.
+     */
+    suspend fun releaseRefusedSparkOnchainProof(request: PaykitPaymentRequest): Boolean = withContext(ioDispatcher) {
+        val identity = currentIdentity() ?: return@withContext false
+        runSuspendCatching {
+            operationMutex.withLock {
+                val proof = loadProofs().lastOrNull {
+                    PubkyPublicKeyFormat.matches(it.identity, identity) && it.requestId == request.id &&
+                        it.sparkWithdrawal && it.paymentStarted && it.proofData == null
+                } ?: return@withLock false
+                releaseUnsentSparkOnchainProofLocked(proof)
+                true
+            }
+        }.onFailure {
+            Logger.warn("Failed to release a refused Spark withdrawal proof", it, context = TAG)
+        }.getOrDefault(false)
+    }
+
+    /** Settles a started Spark proof from Spark's list: completed by its own withdrawal, removed when it never sent. */
+    private suspend fun reconcileSparkOnchainProof(proof: PendingPaykitPaymentProof): Boolean {
+        if (!proof.paymentStarted || proof.proofData != null) return false
+        val address = proof.onchainAddress ?: return false
+        val amount = proof.onchainAmountSats ?: return false
+        val outcome = lightningRepo.sparkWithdrawalOutcome(
+            address,
+            amount,
+            proof.onchainMatchingTransactionIdsBeforeAttempt,
+        )
+        // The request's allowance attempt is settled first: a failed ledger write keeps the proof for the next pass.
+        return when (outcome) {
+            is SparkWithdrawalOutcome.Sent -> {
+                allowanceExecutor.get().onchainSendSettled(proof.identity, proof.requestId, outcome.txid)
+                completeSparkOnchainProofLocked(proof, outcome.txid)
+            }
+            SparkWithdrawalOutcome.Unsent -> {
+                releaseUnsentSparkOnchainProofLocked(proof)
+                false
+            }
+            SparkWithdrawalOutcome.Unknown -> false
+        }
+    }
+
+    private suspend fun releaseUnsentSparkOnchainProofLocked(proof: PendingPaykitPaymentProof) {
+        allowanceExecutor.get().onchainSendReleased(proof.identity, proof.requestId)
+        Logger.info("Released a Paykit proof whose Spark withdrawal never sent", context = TAG)
+        releaseDeniedPrivateConsumption(proof)
+        removeProofsLocked { it == proof }
+        // The pending screen of an uncertain Spark send waits on this to fail it.
+        val release = PaykitSparkWithdrawalRelease(proof.identity, proof.requestId)
+        _sparkWithdrawalReleases.update { if (release in it) it else it + release }
+    }
+
+    private suspend fun completeSparkOnchainProofLocked(proof: PendingPaykitPaymentProof, txid: String): Boolean {
+        val proofs = loadProofs().toMutableList()
+        val index = proofs.indexOf(proof)
+        if (index < 0) return false
+        val completed = proof.copy(
+            paymentIdentifier = txid.lowercase(),
+            proofData = txid.lowercase(),
+            onchainAcceptanceVerified = true,
+        )
+        proofs[index] = completed
+        // The pending screen of an uncertain Spark send waits on this resolution.
+        return persistAndSubmit(listOf(completed), proofs).also { publishOnchainResolution(completed, txid) }
+    }
+
     suspend fun completeLightningPayment(paymentHash: String, preimage: String?) = withContext(ioDispatcher) {
         if (preimage == null) return@withContext
         if (!preimage.matchesPaymentHash(paymentHash)) {
@@ -1193,7 +1357,10 @@ class PaykitPaymentProofRepo @Inject constructor(
         }.getOrElse { return@withContext }
         if (snapshot.isEmpty()) return@withContext
         finishDeniedHardwarePreparations(snapshot)
-        snapshot.filter { it.kind == PaykitPaymentProofKind.Onchain && it.onchainWalletId == WalletScope.default }
+        snapshot.filter {
+            it.kind == PaykitPaymentProofKind.Onchain && it.onchainWalletId == WalletScope.default &&
+                !it.sparkWithdrawal
+        }
             .forEach { proof ->
                 val txid = proof.proofData ?: attempt?.txid
                 val validCompletedProof = proof.paymentStarted && proof.proofData?.isHex(HASH_BYTE_COUNT) == true &&
@@ -1261,6 +1428,9 @@ class PaykitPaymentProofRepo @Inject constructor(
         activityReady: Boolean,
     ): Boolean {
         if (proof.hardwareDispatchDenied) return false
+        if (proof.sparkWithdrawal) {
+            return if (proof.proofData != null) submitReady(proof) else reconcileSparkOnchainProof(proof)
+        }
         if (proof.kind == PaykitPaymentProofKind.Onchain && proof.onchainWalletId == WalletScope.default &&
             !activityReady
         ) {
@@ -1459,6 +1629,10 @@ class PaykitPaymentProofRepo @Inject constructor(
         }
     }
 
+    fun consumeSparkWithdrawalRelease(release: PaykitSparkWithdrawalRelease) {
+        _sparkWithdrawalReleases.update { it - release }
+    }
+
     fun consumeOnchainPaymentResolution(resolution: PaykitOnchainPaymentProofResolution) {
         _onchainPaymentResolutions.update { it - resolution }
     }