[ovitrif]

Stacked on #1697
Twin: synonymdev/bitkit-ios#1217

This PR adds the Spark emergency exit on top of Spark (#1697): if the Spark operators stop working, Spending moves to Savings on-chain without them, which is what Spark's trust model rests on. It was split out of #1697 so that Spark can be reviewed and merged on its own; the code is the same as #1697's head before the split, merged with master.

Description

Screens and flow

• Lightning Connections › Spark shows Emergency exit under Transfer to Savings while Spark holds funds or has recoverable funds, and leads to the exit's progress while one runs or its result is still unseen.
• The flow is an explainer, a quote, fee funding, a confirm swipe and a progress screen:
  • The quote comes from the SDK's prepareRecoverFunds for every leaf at its fastest fee rate to a fresh Savings address: amount to exit, network fees, you receive about, fee funding needed and what stays on Spark. Continue is blocked when nothing can be exited or the fees exceed the value.
  • Fee funding: pay from Savings when it covers the funding and its fee, or fund a shown address from another wallet.
  • The swipe writes the exit record and the transfer before any payment.
  • Progress shows the steps, the timelock countdown, rejections, a top-up address when more fees are needed, and the result.

Driving the exit

• Drives the exit with a state machine that builds once the funding confirms, saves every build before broadcasting, broadcasts ready steps as packages (/v1/txs/package) or single transactions to the SDK's own chain hosts (mempool.space then blockstream.info on mainnet, Spark's mempool on regtest), rebuilds a diverged recovery as a new generation that never sends the old hex again, and ends, done or failed, by sweeping leftover fee funding to Savings. Without the SDK (operators down at connect, or a background start) it still broadcasts the stored, signed steps whose parents confirmed and whose timelock matured.
• Publishes a step without the SDK only once its relative timelock matured from its parent's confirmation, stops resending a step whose input someone else spent (the next check rebuilds it), and never counts a not-yet-final answer as a rejection.
• Rebuilds from the same funding when the exit's fee chain lost a race: when another wallet whose leaves share a tree node gets its package for that node confirmed, our CPFP child for it is dropped and every later step spending its change can never confirm, while the SDK check still answers Valid. The exit detects that child (node confirmed, child unknown to every chain host) before broadcasting and rebuilds, never resending the dead transactions. As a safety net, a step whose parents confirmed that comes back unpaid (min relay fee not met, 0 < …) or with missing inputs 3 times in a row rebuilds once; those answers count as no rejection until that rebuild, and a step stuck that way lets the deadline alarm fire, since without the SDK nothing rebuilds it.
• Takes Spark off Lightning during an exit: no sends, receives or deposits on Spark, its balance shows as in transfer to Savings with the countdown on Home and Savings, and Spark reconnects with leaf optimization off until the exit ends, so no optimization swap hands an exiting leaf to someone else.
• Waits, before quoting an exit, until no leaf optimization runs and the counter-swap of one cut short is claimed (the SDK's 300 s grace), then syncs, so value in flight is not left out of the exit; the quote screen says it is waiting. Starting the exit also waits for a running optimization before Spark reconnects. While an exit runs, Progress shows Spark's balance beyond the quote's leaf total as outside the exit.

Background run on Android

• Runs the exit to completion with Bitkit closed, so users need not open it until it finishes. The record (spark-exit.json, the same JSON as iOS, with the recovery in spark-sdk's serde shape) is reloaded on launch and the exit ticks every minute while Bitkit is open. While it is closed, a WorkManager job runs every 15 minutes from a cold process, also after the app is killed or the phone restarts: it publishes the stored steps, connects Spark alone (never the node) to check, sign and rebuild, and saves after each broadcast, so a killed run sends nothing twice. App start, boot and app updates queue the job again when an exit runs.
• Adds the SparkExitWorker WorkManager job and a BOOT_COMPLETED/MY_PACKAGE_REPLACED receiver that queue it again while an exit runs, and hooks the foreground loop to the app's start and stop.

Notifications, funding and the leftover sweep

• Notifies only when the background run falls behind: an alarm 12 blocks into the operators' ~50-block window of the next step, pushed back by every run that keeps up, fires when none did and names why (steps refused again and again, no network, background restriction, battery saver) and the time to open Bitkit by; needing more fee funding is notified at once. The swipe asks for notification permission, and Progress notes background restriction, battery saver, battery optimization and notifications off. The explainer and Progress say the exit runs in the background and Bitkit notifies you if it needs you.
• Pays the exit's CPFP fees from a key on its own account, m/84'/{coin}'/7797'/0/<index>, derived from the wallet seed with bitkit-core, so ldk-node never spends the funding UTXO or the CPFP change chained back to it; only the path index is kept, never the key.
• Asks, when a rebuild needs more fees, for a top-up of only what the SDK's required total lacks beyond what the funding address still holds (adopted inputs and the CPFP change of every generation count as held; several small payments count as new funding), instead of the whole total again.
• Shows Paid from savings, waiting for confirmation, with the funding transaction, on Progress once the app has paid the fee funding, and Payment seen, waiting for confirmation, for a payment from another wallet seen in the mempool, instead of asking for the funding again; it asks only for what is still missing once that confirms, at least the funding output's 294-sat dust limit, also on the first tick after a build ends short, and shows what arrived so far (₿ X of ₿ Y received, send ₿ Z more) on Progress and the funding screen, where Continue waits until the funding is covered.
• Gives each exit its own funding key index, kept in the record and the app cache, so a later exit never reuses an earlier one's funding address or mixes in its leftover; restarts sign with the record's index, and records written with index 0 still load.
• Records the fee funding paid from Savings as an ordinary payment in Activity, not a transfer to Spending, and says the exit takes up to 4 weeks.
• Sweeps fee funding an exit leaves at its funding address (CPFP change after a rebuild, or a branch the operators published) to Savings when it ends, background runs included, signed by the SDK's single-key signer over a PSBT Bitkit builds, at the exit's fee rate once every UTXO there confirmed. It is saved before it is sent and sent again each run until a node accepts it; nothing is sent when what arrives would be under the output's dust limit. Background runs keep going after the exit ends until the sweep is accepted, without starting Spark.
• Keeps a finished exit's result reachable from Emergency exit and the Spark screen until its leftover sweep confirms or is under dust, and shows the sweep's state there: sending, sent with its transaction ID, or kept as dust at the funding address. An exit that failed or lost a leaf stays reachable until its result was opened once. Only then does Emergency exit open a fresh explainer.
• A failed or partly lost exit keeps its result and notifies until the user opens it.

Lost leaves and fee-ladder leaves

• Leaves out a leaf an older owner of these funds already claimed once two rebuilds reproduce its spent refund, says on Progress what can't be recovered and notifies once with the amount, as it does when an exit fails, also while Bitkit is open; a leaf the SDK refuses to exit is left behind and the rest rebuilt.
• Names on the quote what it can't exit: leaves too small to pay their own fees and Spark's balance beyond them.
• Warns 12 blocks after a step matures, inside half the 50-block window on every network.
• Drops a leaf the SDK refuses to exit, such as a fee-ladder leaf whose refund cannot pay its own fee at the rebuild's rate, and prepares the rest again; when the refused leaf can't be told from the error, it prepares the recoverable leaves instead and leaves out the rest. The exit records how many leaves it left behind.

SDK facts this relies on

• prepareRecoverFunds(All), used for the quote, can't abort: leaves that can't pay their own exit are listed under skipped (FeeExceedsValue) and the rest is quoted.
• A Specific rebuild can abort as a whole on an anchorless fee-ladder leaf; the app drops that leaf and retries with the rest.

Out of Scope

• Emergency exit translations: its strings carry the English text in every locale, as on iOS; the Spark strings in feat: add spark via breez sdk #1697 are translated.
• A manual fee bump for a running exit: rebuilds use the fee rate chosen at the quote.

Risks for review

• Emergency exit on mainnet. No exit has run on mainnet. Mainnet leaves carry fee ladders, a different refund path that Spark's hosted regtest and the public operator code used for the local runs do not have, and package relay at mempool.space and blockstream.info is untested with a real exit: a refused package keeps its step ready, the next host is tried, and the progress screen shows the error after 3 rejections. The exit can take up to about 4 weeks (local regtest exits took about 1,900–2,000 blocks from the first broadcast to the sweep, about 13–14 days at mainnet block times), and about 50 blocks after a step matures the operators may publish their own version, paid from the leaf; the 15-minute background work publishes inside that window, with the deadline alarm as fallback when Doze or the standby bucket holds it back. A user who restricted Bitkit's background use, or force-stopped it, gets neither until the next launch (Progress says so), and without notification permission the fallback is silent. At 2 sat/vB, leaves under about 4,096 sats cost more to exit than they hold and stay on Spark, so an exit of a typical balance recovers about 75% of it after fees.

Design

N/A — no design yet. The emergency exit screens follow the Transfer to Savings screens; docs/screens-map.md lists them as todo.

Preview

Emergency exit on Spark's regtest: the explainer, quote and Fund from another wallet (1adfc47); Pay from savings, the swipe, Progress waiting for the paid funding and then publishing (3e60f04); and the earlier exit waiting for its timelock with the background notes and the countdown on Savings (3e60f04).

Fund from another wallet	Pay from savings	Running exit
e1-explainer-quote-funding2x.mp4	e2-pay-savings-progress2x.mp4	e3-running-exit2x.mp4

A full exit on a local regtest stack (4771ead, older copy): relaunch after the operators published the refunds first, the rebuild and the sweep to Savings, and the result of the first exit.

Redo and sweep	Exit complete
q3-redo-sweep2x.mp4

Screens

Dark mode, default size.

Spark detail during an exit

Intro	Quote with the can't-exit note	Funding choices	Funding address

Confirm	Notification prompt	Running	Needs funding

Needs funding, partial	Paid from savings	Payment seen	Done

Leftover sending	Leftover swept	Stopped	Stopped, balance stays on Spark

Lost to an older owner

QA Notes

Setup

• A dev build on Spark's regtest chain, set up as in feat: add spark via breez sdk #1697's QA Notes (ESPLORA_URL and the faucet), runs the exit from the explainer to Progress; the timelocks of about 1,900 blocks keep a full exit out of reach there.
• The full exits ran on a local regtest stack: spark-sdk 0.27.2 against the last public Spark operator (1 Oct), patched to accept 0.27.2's status filters and with fee ladders off, since the current operator image is private. Every leaf there is an anchored, pre-ladder leaf.

Journeys

• new transfer/spark-emergency-exit.xml — with a Spark balance, Emergency exit opens the explainer, the quote lists amount, fees and what arrives, and funding shows Pay from savings and a funding address from another wallet; stops before the swipe.

Manual Tests

• 27. Dev on Spark's regtest chain, Spark funded from the faucet → Emergency exit, fund from another wallet with the faucet, swipe → Progress shows fee funding confirmed, then publishing with confirmed steps counting up and Ready in a countdown; kill and reopen the app mid-exit → it continues without sending a step twice; at the end Savings receives about the quoted amount and the transfer settles — hours of regtest blocks.
• 28. Same as 27 with Pay from savings → the funding payment shows as an ordinary payment, not a transfer to Spending, and the exit starts once it confirms — Spark's regtest chain.
• 29. During an exit → Spending shows the Spark balance as in transfer to Savings, Lightning receives and sends do not use Spark, and Transfer to Spending shows the Transfer Unavailable sheet — a running exit.
• 30. Exit started but not funded → Cancel exit on Progress puts Spark back as it was — needs a Spark balance.
• 31. Dev, an exit running → kill Bitkit from the background (not Force stop) → the next background run logs Driving the Spark exit in background, connects Spark and checks the exit with no screen open; with Wi-Fi and data off past the deadline alarm, a notification names the time to open Bitkit by — a running exit.
• 32. Dev on Spark's regtest chain, Emergency exit with Pay from savings → right after the swipe Progress shows Paid from savings, waiting for confirmation, with the transaction ID and no address or QR; with Fund from another wallet, a payment seen in the mempool shows Payment seen, waiting for confirmation — Spark's regtest chain.
• 33. An exit that ends with leftover fee funding (a Redo that needed no funding) → Emergency exit and the Spark screen still open the result, which shows the sweep sending, then sent with its transaction ID, or kept as dust; a fresh explainer shows only after that — needs an exit to end, about 2,000 regtest blocks.
• 34. A second exit on the same wallet → its funding address differs from the first exit's — two exits.
• 35. Relaunch Bitkit with an exit whose refunds wait for their timelock → before Spark reconnects the log shows no non-BIP68-final or missingorspent broadcast — a running exit near its timelock.
• 36. Mainnet, a fresh wallet with about 50,000 sats on Spark, in a low-fee week → Emergency exit to the end, with the phone charged and online for about two weeks → each step confirms, none is published by the operators first, and the sweep lands in Savings — mainnet funds, fee-ladder leaves and real block times.

Automated Checks

• added SparkExitRecordTest.kt — the record round trips with every phase and status, the recovery keeps spark-sdk's serde shape, a recovery written by the Breez CLI and a record written by Bitkit iOS are read, an unknown version is refused, and the store saves atomically and sets an unreadable record aside
• added SparkExitDriverTest.kt — waits for confirmed funding, builds and saves before broadcasting, Valid broadcasts ready steps once until due, rejections surface after 3, Done ends with leftover funding, Redo rebuilds as a new generation that never sends the old hex (also without the SDK), a rebuild short of fees asks only for what the SDK's total lacks beyond what the address holds (50 sats on the local regtest run's numbers, 2,000 after a Redo whose input lives on as 13,000 of change) and adopts several small top-ups together, the tick that ends the exit sweeps its leftover until a node accepts it, dust is not swept, a top-up ignores CPFP change, cooperative failures retry, an unverified leaf waits, a restart mid-exit resumes from the file without repeating broadcasts, and the keyless pass broadcasts only steps whose parents confirmed and timelocks matured
• added SparkExitFundingTest.kt — what arrives, the fees and the fee funding of a quote, the uneconomic gate, the funding shortfall, the countdown height, the funding UTXO choice, whether Savings can pay, the ETA per network, the funding path, WIF decoding and CPFP child txids
• added SparkExitChainTest.kt — packages go out as a raw JSON array and single steps as plain hex, the unversioned path and the next host are tried, a node's refusal wins over an unavailable host, tip and UTXOs are read, and node answers are classified
• added SparkExitRepoTest.kt — loading settles exit transfers no running exit owns, including the transfer of a record set aside as unreadable; a background run from a cold start (Spark not connected, no UI) publishes from the stored recovery against a mock regtest mempool, connects Spark and checks, and a restarted process sends nothing twice; runs whose steps keep being refused stop pushing the deadline alarm back; a background run of an ended exit with leftover to sweep keeps going without starting Spark
• added SparkExitSweepTest.kt — bech32, bech32m, P2PKH and P2SH addresses decode to their scripts, dust limits follow Bitcoin Core per output type, a sweep pays its inputs less the fee and skips dust, the signed transaction carries the signer's witnesses and keeps the unsigned txid, and an unsigned input is refused
• added SparkExitAlertsTest.kt — a stalled exit's notification names refused steps, no network, background restriction or battery saver (battery optimization alone names no cause), asks for fee funding, and stays quiet when nothing needs the user
• added SparkExitRegtestTest.kt (unit, opt-in with SPARK_EXIT_REGTEST=1) — Spark's regtest mempool answers the tip and a funding address, and its node's per-transaction answer to a package is read as retry later
• added SparkExitRegtestTest.kt (instrumented, opt-in with -e sparkExitRegtest true) — on a device against Spark's regtest, a new wallet's quote has nothing to exit, the funding key derives with bitkit-core into a working CPFP signer, and a leftover sweep PSBT is signed and finalized by the SDK's singleKeyCpfpSigner
• updated SparkExitDriverTest.kt, SparkExitFundingTest.kt, SparkExitRecordTest.kt, SparkExitRepoTest.kt, SparkExitChainTest.kt (cc2641c) — Done after a Redo that needed no funding sweeps the earlier generation's change in one transaction, an exit that ended while its funding address could not be read ends again once it can, each exit takes a funding key index no earlier exit used and a restart signs with its own record's, without the SDK a refund waits for its CSV from its parent's confirmation and a step whose input someone else spent is not sent again, a refund an older state spent ends the exit after two rebuilds reproduce it, a lost leaf or one recoverFunds refuses is left out and the rest rebuilt, a rebuild whose every leaf cannot be exited fails, Progress waits for a payment from savings or one seen in the mempool and asks only for what is missing, the quote names what it skips, and the deadline warns within half the 50-block window on every network
• updated SparkExitDriverTest.kt, SparkExitChainTest.kt, SparkExitRecordTest.kt, SparkExitRepoTest.kt, SparkExitViewModelTest.kt (2ed4673, f541952, 0baad3f) — two packages for one shared node where theirs confirms and ours is dropped rebuild from the same funding without resending the dead transactions, and wait for the rebuild interval sending nothing meanwhile; a child still in the mempool is not dead; a step unpaid 3 times in a row rebuilds once and then surfaces, and any other answer resets the count; a transaction is unknown only when every host answers 404; only a zero-fee refusal reads as unpaid; the new record fields round trip; a background run whose step keeps going unpaid without Spark lets the deadline alarm fire; a tick that ends short of 68 sats asks for 294 at once, and Progress asks for at least 294 before the funding address was read
• updated SparkExitViewModelTest.kt (4df5c75) — a stopped exit that lost a 32,768-sat leaf and could not exit 1,696 says ₿ 1 696 stays on Spark, from Spark's live balance, and claims nothing when only the lost leaf is left
• added SparkRepoTest.kt case — an exit quote waits for a running leaf optimization and out the counter-swap grace of one cut short before it syncs
• added SparkExitViewModelTest.kt — after Fund from another wallet, Back and Continue offer both funding choices again
• updated LightningConnectionsViewModelTest.kt, AppViewModelSendFlowTest.kt — construct the exit repository

QA

Local regtest exits, from the QA write-up (spark-sdk 0.27.2 against the last public operator, Android emulator):

Case	Result
Quote with all 3 operators stopped	✅ 90,112 to exit, 4,537 fees, 5,713 funding, 9,888 staying on Spark
Fee funding from another wallet	✅ exactly 5,713
Kill mid-exit, relaunch	✅ continued without sending a step twice
Full exit to Savings	✅ 91,288 swept, 1,907 blocks from the first broadcast (about 13 days at mainnet block times)
Operators publish the refunds first (Redo)	✅ generation 2, no funding needed, 93,200 swept
Top-up after a short build (on 5edd5a8ce)	✅ asked only for the 68 sats missing, with a notification
Leftover sweep (on 5edd5a8ce)	✅ 1,626 and 626 back to Savings
Pay from savings, then new funding address per exit (on 5edd5a8ce)	✅ paid, waiting for confirmation, with the txid
Partial funding (on f1507f29d)	✅ ₿ 500 of ₿ 1,329 received, send ₿ 829 more; Continue waits
Single leaf lost to an older owner (on f1507f29d)	✅ leaf dropped, 558 swept back, Failed, one notification, result kept until opened

The same write-up's headless runs on the SDK's calls show a stale refund from an older owner winning when the app sleeps past the 100 blocks after a maturity with the operators down, which the lost-leaf handling above now ends with a Failed exit instead of an endless Redo.

🟢 Exit start and funding from another wallet, Pay from savings, Running exit in the background

Exit start and funding from another wallet

On 1adfc47 on Spark's regtest chain (J9's steps by hand): with 79,703 on Spark the quote showed 65,536 to exit, 8,923 network fees, about 56,613 to receive, 9,211 fee funding and 14,167 staying on Spark, and Fund from another wallet showed the funding address and amount. Recording in Preview.

---

Pay from savings

On 3e60f04, a fresh wallet with 69,802 on Spark (part of 32: Pay from savings): the quote named the 12,458 it can't exit, the swipe asked for notification permission, Progress showed Paid from savings, waiting for confirmation, with the transaction ID and no QR until the funding confirmed about a minute later, then published 1 of 23 steps. Recording in Preview.

---

Running exit in the background

On 3e60f04, the 4-leaf exit started on 326a6aa (21 of 30 steps confirmed, waiting for the timelock) loaded on the new build: Progress showed the background, battery optimization and notifications-off notes, and Savings showed From Spending (±4d) 90,400 (part of 29: the countdown). On bd931ac, with Bitkit's process killed, the periodic job published nothing due, connected Spark alone, checked the exit as Valid, saved the record and ended in 9 seconds; after a reboot the job and the deadline alarm came back, and background restriction held both (part of 31: the background run). The 326a6aa run found three bugs, fixed there: the fan-out confirm Spark's regtest mempool never reported, the foreground loop that never started, and the timelock step shown as done too early. Recording in Preview.

---

🟢 Full exit with the operators down, Redo after the operators publish first, Funding short then topped up

Full exit with the operators down

On 4771ead, with a local config patch not in this PR, on a local regtest stack (spark-sdk 0.27.2 against the last public Spark operator, fee ladders off, since the current operator image is private): with the 3 operators stopped the quote showed 90,112 to exit, 4,537 fees and 5,713 funding; funded exactly from another wallet, the exit built 25 transactions, resumed after a force-stop without sending a step twice, published each refund within a minute of maturity, and swept 91,288 to Savings 1,907 blocks after the first broadcast, ending on Exit complete with 18 small amounts left on Spark. Screenshot in Preview.

---

Redo after the operators publish first

On 4771ead, a second exit paid from savings was force-stopped until 2,000 blocks past maturity, the operators' watchtower published all 5 refunds, and the relaunch rebuilt as generation 2 with no funding and swept 93,200 to Savings. It left 3,514 sats of funding change unswept and hidden after Done, on the first exit's funding address, which cc2641c fixes (33, 34). Recording in Preview.

---

Funding short then topped up

On the same stack, a harness making Bitkit's SDK calls showed a rebuild needing 9,085 sats with 9,035 held over 5 UTXOs, then reaching Done after a 1,000 sat top-up; Bitkit asked for the whole total instead of the 50 missing, fixed in aec3163.

---

🟢 Pay from savings after viewing the funding address

Pay from savings after viewing the funding address

On 1adfc47, after Fund from another wallet, Back and Continue reopened the funding address with no Pay from savings button. Fixed in b4ec299, which resets the choice on Back; SparkExitViewModelTest.kt covers it, not rerun on a device.

🟠 Exit end and notifications on the new build

Exit end and notifications on the new build

Not run: on Spark's regtest the running exits wait for timelocks of about 1,900 blocks, so the result kept reachable with its sweep state (33), a second exit's new funding address (34) and the relaunch without early refunds (35) rest on the unit tests; the deadline and funding notifications (rest of 31) are covered by SparkExitAlertsTest.kt, and Payment seen for an outside payment (rest of 32) by SparkExitFundingTest.kt.

---

Open

• Hosted-regtest exit: not run yet. It needs a funded wallet on Spark's hosted regtest, whose faucet credentials only Breez's CI holds.
• Mainnet exit (Manual Test 36): not run yet. It needs a fresh wallet with about 50,000 sats on Spark, a low-fee week and the phone online for about two weeks.
• Fee-ladder leaves: mainnet leaves carry fee ladders, and both Spark's regtest and the public operator used for the local runs are pre-ladder, so the ladder refund path runs only in unit tests.
• Translations: the emergency exit strings are English in every locale.

Models used

• Planning/scoping: claude-opus-5-5 (reasoning: low)
• Implementation: claude-opus-5-5 (reasoning: low)
• Review: Not performed

[github-actions]

Regtest APK

Built from 4df5c75 (run).

Download bitkit-dev-debug universal APK (expires in 30 days).

[ovitrif]

QA on a92ee43: dev build on an Android 15 emulator, Spark on its hosted regtest, Savings funded with 200,000 sats on staging regtest.

• 🟢 J1 spark-transfer-to-spending.xml from feat: add spark via breez sdk #1697, to check the exit's gating leaves the transfer flow alone: every step held, with the same figures as on feat: add spark via breez sdk #1697 (Max 199,635, up to 696 Instant, ≈ 99 Later), and Savings › Transfer To Spending opened the amount screen with no intro.
• 🟠 spark-emergency-exit.xml: stopped at step 6. With a ₿ 0 Spark balance the Spark screen hides Emergency exit and disables Transfer to Savings, as designed; the rest needs a Spark balance from Lightspark's regtest faucet.

J1 on this PR, and the exit journey up to the Spark screen with no balance (2x speed).

J1 flow	No intro on the second entry	Exit journey, ₿ 0 on Spark
j1-exit-a2x.mp4	j1-exit-b2x.mp4	exit-journey2x.mp4