feat: pay contacts via spark

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

@@ -18,6 +18,7 @@ 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.utils.Logger
 import javax.inject.Inject
 import javax.inject.Singleton
@@ -169,6 +170,8 @@ 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,
 ) {
     fun isContactDetached(activityId: String, walletId: String): Boolean =
         scopedActivityId(walletId, activityId) in detachedActivityContacts

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

@@ -2331,6 +2331,16 @@ 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)
 

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

@@ -108,6 +108,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(
@@ -297,6 +299,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
@@ -336,12 +380,90 @@ 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)
+    }
+
+    /** 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,
+        )
+        return when (outcome) {
+            is SparkWithdrawalOutcome.Sent -> completeSparkOnchainProofLocked(proof, outcome.txid)
+            SparkWithdrawalOutcome.Unsent -> {
+                Logger.info("Released a Paykit proof whose Spark withdrawal never sent", context = TAG)
+                removeProofsLocked { it == proof }
+                false
+            }
+            SparkWithdrawalOutcome.Unknown -> false
+        }
+    }
+
+    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
+        return persistAndSubmit(listOf(completed), proofs)
+    }
+
     suspend fun completeLightningPayment(paymentHash: String, preimage: String?) = withContext(ioDispatcher) {
         if (preimage == null) return@withContext
         if (!preimage.matchesPaymentHash(paymentHash)) {
@@ -1182,7 +1304,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 &&
@@ -1250,6 +1375,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
         ) {

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

@@ -0,0 +1,86 @@
+package to.bitkit.repositories
+
+import com.synonym.bitkitcore.PaykitEndpoint
+import com.synonym.bitkitcore.PaykitRoute
+import com.synonym.bitkitcore.PaykitRouteRequest
+import com.synonym.bitkitcore.ServiceRouteLeg
+import com.synonym.bitkitcore.paykitRoutePayment
+import kotlinx.coroutines.CoroutineDispatcher
+import kotlinx.coroutines.withContext
+import to.bitkit.di.IoDispatcher
+import to.bitkit.env.Env
+import to.bitkit.ext.runSuspendCatching
+import to.bitkit.models.toCoreNetwork
+import to.bitkit.utils.AppError
+import to.bitkit.utils.Logger
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Picks how to pay a Paykit contact through bitkit-core's Paykit router: directly from a balance the wallet holds,
+ * or through a Spark withdrawal to the contact's on-chain endpoint when no balance reaches the contact. The router
+ * makes no network calls; the app quotes each Spark leg and runs the one the router returns.
+ */
+@Singleton
+class PaykitRouteRepo @Inject constructor(
+    @IoDispatcher private val ioDispatcher: CoroutineDispatcher,
+    private val sparkRepo: SparkRepo,
+) {
+    companion object {
+        private const val TAG = "PaykitRouteRepo"
+    }
+
+    /** Whether Spark holds a balance it can send, so a Spark leg may reach a contact no other balance reaches. */
+    val canRouteThroughSpark: Boolean
+        get() = sparkRepo.state.value.let { it.isReady && it.sendableSats > 0uL }
+
+    suspend fun route(
+        amountSats: ULong,
+        endpoints: List<PaykitEndpoint>,
+        lightningSpendableSats: ULong,
+        onchainSpendableSats: ULong,
+        quoteServiceLegs: Boolean,
+    ): Result<PaykitRoute> = withContext(ioDispatcher) {
+        runSuspendCatching {
+            paykitRoutePayment(
+                request = PaykitRouteRequest(
+                    amountSat = amountSats,
+                    contactEndpoints = endpoints,
+                    lightningSpendableSat = lightningSpendableSats,
+                    onchainSpendableSat = onchainSpendableSats,
+                    serviceLegs = if (quoteServiceLegs) serviceLegs(endpoints, amountSats) else emptyList(),
+                ),
+                network = Env.network.toCoreNetwork(),
+            )
+        }
+    }
+
+    /** Spark withdrawals to the contact's on-chain endpoints, each quoted with its fee. */
+    private suspend fun serviceLegs(endpoints: List<PaykitEndpoint>, amountSats: ULong): List<ServiceRouteLeg> =
+        endpoints.filter { MethodId.fromRawValue(it.methodId)?.isOnchain == true }.mapNotNull { endpoint ->
+            sparkRepo.withdrawalRouteLeg(endpoint, amountSats)
+                .onFailure { Logger.warn("No Spark route to '${endpoint.methodId}'", it, context = TAG) }
+                .getOrNull()
+        }
+
+    /**
+     * Runs a service leg the router picked to the [contact] and returns the txid that pays them; [onBeforeSend] runs
+     * once the leg is prepared, right before it sends.
+     */
+    suspend fun payServiceLeg(
+        leg: ServiceRouteLeg,
+        contact: String?,
+        tags: List<String> = emptyList(),
+        onBeforeSend: suspend () -> Boolean = { true },
+    ): Result<String> = when (leg.service) {
+        SparkRepo.ROUTE_SERVICE -> sparkRepo.withdraw(
+            address = leg.endpoint.value,
+            amountSats = leg.deliveredSat,
+            contact = contact,
+            maxDebitSats = leg.debitSat,
+            tags = tags,
+            onBeforeSend = onBeforeSend,
+        )
+        else -> Result.failure(AppError("Unsupported route service '${leg.service}'"))
+    }
+}