feat: spark emergency exit

Bitkit/AppScene.swift

@@ -609,6 +609,35 @@ struct AppScene: View {
                 await pubkyProfile.retrySessionRestoration()
             }
             .task(id: [scenePhase == .active, network.isConnected, wipeCoordinator.isGateUp]) { await pollIncomingPaykitPaymentRequests() }
+            .task(id: [scenePhase == .active, SparkExitManager.shared.needsDriving]) {
+                guard scenePhase == .active else { return }
+                await SparkExitManager.shared.runWhileActive()
+            }
+            .task(id: [
+                SparkExitManager.shared.opensProgress,
+                SparkExitManager.shared.showsResult,
+                SparkExitManager.shared.hasLoadedRecord,
+                isLockedForDeepLinks,
+                wallet.walletExists == true,
+            ]) {
+                // A tapped exit notification opens the exit once the wallet is unlocked and its record is loaded.
+                let exit = SparkExitManager.shared
+                guard exit.opensProgress, wallet.walletExists == true, !isLockedForDeepLinks else { return }
+                switch SparkExitManager.notificationOpen(
+                    opensProgress: exit.opensProgress,
+                    showsResult: exit.showsResult,
+                    hasLoadedRecord: exit.hasLoadedRecord
+                ) {
+                case .wait:
+                    return
+                case .drop:
+                    exit.opensProgress = false
+                case .open:
+                    exit.opensProgress = false
+                    navigation.reset()
+                    navigation.navigate(.sparkExitProgress)
+                }
+            }
             .task(id: foregroundContactSession) {
                 shopContactImport?.task.cancel()
                 shopContactImport = nil

Bitkit/Assets.xcassets/icons/hourglass-simple.imageset/Contents.json

@@ -1,7 +1,7 @@
 {
   "images" : [
     {
-      "filename" : "hourglass-simple.pdf",
+      "filename" : "hourglass-simple.svg",
       "idiom" : "universal"
     }
   ],
@@ -10,6 +10,7 @@
     "version" : 1
   },
   "properties" : {
+    "preserves-vector-representation" : true,
     "template-rendering-intent" : "template"
   }
 }

Bitkit/BitkitApp.swift

@@ -73,6 +73,7 @@ class AppDelegate: NSObject, UIApplicationDelegate {
     func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool
     {
         UNUserNotificationCenter.current().delegate = self
+        SparkExitManager.registerBackgroundTask()
 
         // Check notification authorization status at launch and re-register with APN if granted
         UNUserNotificationCenter.current().getNotificationSettings { settings in
@@ -163,6 +164,8 @@ extension AppDelegate: UNUserNotificationCenterDelegate {
                 PaykitSubscriptionNotificationTargetStore.save(target)
             }
             NotificationCenter.default.post(name: .paykitSubscriptionPaymentDue, object: nil, userInfo: userInfo)
+        } else if userInfo["bitkit_action"] as? String == SparkExitManager.notificationAction {
+            Task { @MainActor in SparkExitManager.shared.opensProgress = true }
         } else {
             PushNotificationManager.shared.handleNotification(userInfo)
         }

Bitkit/Constants/Env.swift

@@ -296,6 +296,27 @@ enum Env {
             .appendingPathComponent("wallet\(walletIndex)/spark-exit-restore.json")
     }
 
+    /// The running Spark emergency exit, if any: its signed recovery and how far it got.
+    static func sparkExitRecord(walletIndex: Int) -> URL {
+        appStorageUrl
+            .appendingPathComponent(networkName)
+            .appendingPathComponent("wallet\(walletIndex)/spark-exit.json")
+    }
+
+    /// Earlier Spark exits' funding addresses that hold, or may still receive, coins, kept past the exit record.
+    static func sparkExitEarlierAddresses(walletIndex: Int) -> URL {
+        appStorageUrl
+            .appendingPathComponent(networkName)
+            .appendingPathComponent("wallet\(walletIndex)/spark-exit-earlier-addresses.json")
+    }
+
+    /// The leaves an older state of the wallet claimed in an earlier Spark exit, kept out of every later one.
+    static func sparkExitLostLeaves(walletIndex: Int) -> URL {
+        appStorageUrl
+            .appendingPathComponent(networkName)
+            .appendingPathComponent("wallet\(walletIndex)/spark-exit-lost-leaves.json")
+    }
+
     /// Breez SDK API key, set with the `BREEZ_API_KEY` build setting. Spark on mainnet needs it; its regtest does not.
     static var breezApiKey: String? {
         infoPlistValue("BREEZ_API_KEY")

Bitkit/Info.plist

@@ -2,6 +2,16 @@
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
+	<key>BGTaskSchedulerPermittedIdentifiers</key>
+	<array>
+		<string>to.bitkit.spark-exit</string>
+		<string>to.bitkit.spark-exit.processing</string>
+	</array>
+	<key>UIBackgroundModes</key>
+	<array>
+		<string>fetch</string>
+		<string>processing</string>
+	</array>
 	<key>UIDesignRequiresCompatibility</key>
 	<true/>
 	<key>USDT_BRIDGE_NETWORKS</key>

Bitkit/MainNavView.swift

@@ -710,6 +710,12 @@ struct MainNavView: View {
                 case .connections: LightningConnectionsView()
                 case let .connectionDetail(channelId): LightningConnectionDetailView(channelId: channelId)
                 case .sparkConnectionDetail: SparkConnectionDetailView()
+                case .sparkExitIntro: SparkExitIntroView()
+                case .sparkExitQuote: SparkExitQuoteView()
+                case .sparkExitFunding: SparkExitFundingView()
+                case .sparkExitConfirm: SparkExitConfirmView()
+                case .sparkExitProgress: SparkExitProgressView()
+                case .sparkExitFeeBump: SparkExitFeeBumpView()
                 case let .closeConnection(channel: channel): CloseConnectionConfirmation(channel: channel)
                 case .node: NodeStateView()
                 case .electrumSettings: ElectrumSettingsScreen()

Bitkit/Managers/BalanceManager.swift

@@ -26,7 +26,9 @@ class BalanceManager {
     /// Derives the complete balance state including pending transfers
     /// - Returns: BalanceState with all balance calculations
     /// - Throws: Error if balance retrieval fails
-    func deriveBalanceState() async throws -> BalanceState {
+    /// - Parameter exitInTransfer: the running Spark exit's transfer and what it still brings to savings, counted in
+    ///   place of that transfer's fixed amount.
+    func deriveBalanceState(exitInTransfer: (transferId: String, sats: UInt64)? = nil) async throws -> BalanceState {
         let balanceDetails = await MainActor.run { lightningService.balances }
         guard let balanceDetails else {
             throw AppError(message: "Balance details unavailable", debugMessage: "LightningService.balances is nil")
@@ -43,7 +45,8 @@ class BalanceManager {
 
         let (lightningToSubtract, pendingCloseAmount) = await getCloseTransferAmounts(
             transfers: activeTransfers,
-            balanceDetails: balanceDetails
+            balanceDetails: balanceDetails,
+            exitInTransfer: exitInTransfer
         )
 
         // Detect orphan closed channels: channels with lightning balance that are no longer
@@ -138,12 +141,18 @@ class BalanceManager {
     /// - Returns: lightningToSubtract (always subtract from display), pendingAmount (add to total only if on-chain hasn't arrived)
     private func getCloseTransferAmounts(
         transfers: [Transfer],
-        balanceDetails: BalanceDetails
+        balanceDetails: BalanceDetails,
+        exitInTransfer: (transferId: String, sats: UInt64)? = nil
     ) async -> (lightningToSubtract: UInt64, pendingAmount: UInt64) {
         var lightningToSubtract: UInt64 = 0
         var pendingAmount: UInt64 = 0
 
         for transfer in transfers.filter({ $0.type.isToSavings() }) {
+            // A Spark exit has no channel: it is in transfer until its sweep confirms and the exit settles it.
+            if transfer.type == .sparkExit {
+                pendingAmount += Self.sparkExitInTransferSats(transfer, exitInTransfer: exitInTransfer)
+                continue
+            }
             guard let channelId = transfer.channelId else { continue }
 
             let balanceFromLdk = balanceDetails.lightningBalances
@@ -165,6 +174,12 @@ class BalanceManager {
         return (lightningToSubtract, pendingAmount)
     }
 
+    /// The running exit's own transfer counts what it still brings to savings; any other exit transfer its amount.
+    static func sparkExitInTransferSats(_ transfer: Transfer, exitInTransfer: (transferId: String, sats: UInt64)?) -> UInt64 {
+        guard let exitInTransfer, exitInTransfer.transferId == transfer.id else { return transfer.amountSats }
+        return exitInTransfer.sats
+    }
+
     /// Detects "orphan" closed channels - channels that have lightning balance in LDK
     /// but are no longer in the channels list and don't have a Transfer record yet.
     private func getOrphanClosedChannelBalance(