[ovitrif]

Closes #1805

Twin: synonymdev/bitkit-ios#1128

This PR keeps Lightning in Bitkit after Blocktank stopped selling channels: on top of the Blocktank sunset (#1696), Spark becomes the easy option where Transfer to Spending now leads to manual setup. Savings to Spending funds a Breez SDK on Spark wallet through the restored transfer screens, Lightning sends and receives fall back to it whenever no channel can carry the payment. Existing channels keep working until they close, and ldk-node keeps running the on-chain wallet.

The emergency exit lives in the stacked exit PR, #1782, and the Paykit route over Spark in #1754, both stacked on this one.

Description

What ships in 3.2

• Spark via Breez SDK 0.28.0.
• The restored transfer to Spending, with Instant or Later.
• Paykit on Spark.
• The Transfer to Savings selection.
• Breez real-time sync and LNURL off.
• Mainnet chain service https://bitkit.to/electrs.
• The UI pass: bottom buttons stay at the bottom, content scrolls above them.
• The VSS SPARK_EXIT backup category.
• Not here: the emergency exit is in feat: spark emergency exit #1782, and the Paykit route over Spark in feat: pay contacts via spark #1754.

Transfer to Spending on Spark

• Brings back the Transfer to Spending flow the Blocktank sunset removed, wired to Spark: while Spark is ready, the Spending suggestion card opens the Spending Balance intro (first time) and then Funding, which leads with Transfer from Savings and Use Other Wallet above Manual Setup; Transfer from Savings, and the Savings, Spending and hardware wallet transfer buttons, open the Transfer to Spending intro (first time), then the restored amount, confirm and setting-up screens. Without Spark, the entry points keep showing the Transfer Unavailable sheet. The Spark-only amount, confirm and deposit screens are gone, and one view model drives the restored screens.
• Keeps the old amount screen: number pad, 25%, Max and Available, where Max is the most Savings can send to the Spark deposit address after the network fee. The pad and presets stay disabled with no Savings, Continue refuses an amount that does not cover the Instant fee or that Savings no longer cover, with their own copy, and the offline and node-sync states show as before. Funding shows the old No Available Funds dialog when Savings is empty.
• Keeps the old confirm screen and copy, with the swipe and its rotating coin stack and Learn more. The four tiles become Network fees, Spending fee (the Spark claim fee for the chosen speed), To spending (the amount less that fee) and Total (what leaves Savings). Between the tiles and Learn more, two rows pick the speed: Instant, ready in a few minutes, up to the Instant ceiling; Later, after 3 confirmations, about 30 minutes, at the claim at 3 confirmations priced at the half-hour fee rate. Instant is the default. Advanced, the channel bar and the background-setup toggle are dropped, since Spark has no LSP balance and sends no setup push.
• Prices the confirm screen when it appears, when the speed changes and again at swipe, and sends the transaction at the fee rates it showed. When the total rose or To spending fell since it was shown, the swipe pays nothing, the tiles refresh, and the old Fees changed toast asks for another swipe.
• Brings back the setting-up screen with its animation and steps, driven by the Spark deposit. Instant polls the deposit every 5 s for up to 5 minutes: within the ceiling it claims early at once and says Spark is adding it, then shows the old success screen once the deposit is in the balance; above the ceiling, or when the provider reprices it, it shows what Instant costs now with Pay and Wait, never swapping the fee silently; with no early option, or a declined claim, it says Instant isn't available and Spark adds it after 3 confirmations; when Spark never lists the deposit, it says so and that the user can leave. Later makes no claim call. The poll runs in the app scope, so leaving the screen does not drop an Instant claim within the ceiling.
• Restores the Liquidity screen's layout as the Learn more screen, since the Instant or Later choice is real decision information under Spark: it explains the two speeds, repeats the Spark trust note and shows the spending balance bar after this transfer, with Understood.
• Keeps the SDK from claiming early on its own: the wallet-wide claim cap stays at the recommended fee plus 2 sat/vB and drops the 0.2% share. Lowering it below the spread keeps the deposit from being claimed early, and does not hold back its claim at maturity. The Instant ceiling keeps the old formula with the 0.2% share.
• Brings back Transfer to Spending from a hardware wallet: master signs and broadcasts an on-chain send from the hardware wallet to any address (HwSendViewModel.signAndBroadcast takes the address from its caller), so the restored intro, amount, sign and signed screens send to the Spark deposit address, priced from the device's account, with the same speed choice and setting-up screen. The hardware amount step reuses the restored amount screen with its old test tags, instead of a second copy of it. The send is recorded as a transfer.
• Restores hasSeenTransferIntro and hasSeenSpendingIntro in settings and their migration from the React Native app, removed by the sunset.

Spark wallet and Lightning

• Adds the Breez SDK on Spark (breez_sdk_spark:bindings-android:0.28.0) with SparkService and SparkRepo, so that a Spark wallet starts beside the node from the same recovery phrase and passphrase. Spark derives its own keys on m/8797555', so there is no new phrase to back up.
• Moves to Breez SDK 0.28.0, the latest stable release: an expired Lightning invoice Spark refuses now shows "This Lightning invoice has expired." on the send error screen, and a failed Spark sync is logged; the LNURL and data-sync servers stay off.
• Turns off Breez's real-time data sync (realTimeSyncServerUrl = null), its LNURL server (lnurlDomain = null) and its default external input parsers (useDefaultExternalInputParsers = false) in Spark's config on every network, so the app sends no traffic to Breez's data-sync or breez.tips LNURL servers, offers no Lightning address, and the SDK sends nothing the user scans to third-party parsers.
• Builds the SDK on mainnet with Bitkit's own Esplora (https://bitkit.to/electrs) as its chain service, in place of the SDK's default mempool.space and blockstream.info; regtest and staging keep the SDK's default.
• Routes Lightning receives to Spark when no ready channel has the inbound capacity, so the receive sheet shows a Lightning invoice again without channels.
• Routes Lightning sends and their fee estimates to Spark when no channel has the outbound capacity and the Spark balance covers the amount, so users without channels can pay invoices.
• Raises Spark payments as the node's own payment events and records them as Lightning activity, so the received sheet, send success screen and activity list work for both rails.
• Adds the Spark balance to the Spending balance; the most a payment can send is the larger of the channel and Spark balances, since one payment cannot split across rails. Deposits Spark has seen but not yet claimed show as in transfer to Spending.
• Reads a BREEZ_API_KEY build property, so that mainnet builds without a key keep Spark off; regtest builds use Lightspark's hosted regtest, which needs no key.
• Shows Spark at the top of Lightning Connections like a channel: its balance and each deposit in progress with its confirmations and a link to the transaction. Its detail screen shows the provider with a short trust note, pending and claimed deposits with the claim fee, and Transfer to Savings.
• Pays a Lightning invoice from another Spark wallet as a Spark transfer on regtest, where Spark has no Lightning network, so two dev builds can pay each other's invoices; dev builds also show Spark's deposit address on the Spark screen, to fund it from Lightspark's regtest faucet.
• Adds an ESPLORA_URL build property for regtest builds, which puts the node's chain source on an Esplora endpoint, plus scripts/spark-regtest-esplora.py and scripts/spark-regtest-fund.py, so a dev build runs on Spark's regtest chain and QA can fund it and test Savings to Spending and the claim without mainnet.
• Lists a Transfer to Spending deposit as pending in Lightning Connections and the Spending balance as soon as the app broadcasts it, from the txid it already has, and asks Spark to sync at once; Spark's own deposit state takes over when the SDK lists it.
• Draws Spark's balance bar as one full-width spending bar and shows receiving as No limit in the Lightning Connections header, in the same style and with the same arrow as the spending figure, whenever Spark is ready, because Spark receives without inbound liquidity; Receive's amount check no longer asks for more liquidity or a CJIT while Spark can receive.
• Reads BREEZ_API_KEY from the release environment in the release workflow and fails the release when it is missing, so Spark can't ship switched off; internal release builds pass it through when the release-internal environment has it. A repo admin has to add BREEZ_API_KEY to the release environment (and to release-internal for internal builds with Spark).
• Backs up Spark's unilateral exit data to VSS as its own category, SPARK_EXIT, encrypted like the other backups. It is exported once Spark has connected and synced, and again, at most once a minute, whenever the SDK reports UnilateralExitStateChanged; until Spark has synced the backup waits and is not marked as backed up. The first upload in each app session reads the stored backup and merges it into Spark before replacing it, and fails rather than replace a backup it could not read, so a failed or skipped restore never loses the stored exit data. On restore it is imported right after Spark connects, without contacting the operators, so a wallet restored on a new device can still exit on-chain while the operators are unreachable; a failed restore of it shows as an incomplete restore. The category shows in Backup settings only where Spark runs.
• Shows a Spark send whose outcome the SDK did not return as Payment Pending, not as failed, and lets Spark settle it once Payment Pending tracks it: its payment event, or Spark's record after a sync (retried every 30 s while Spark cannot list its payments), ends it as sent or failed, and failed when Spark holds no record of it. A payment event settles its send and records its activity even when the balance read after it fails. The same invoice is never sent twice: a send in flight or pending returns Payment Pending, and one Spark already completed shows as paid.
• Shows Spark and SDK errors on the send error screen with the existing payment failed copy; their text goes to the log only.
• Keeps a Max Lightning send over Spark within the balance: the SDK prices sending the whole balance with fees included, and Max leaves that routing and service fee.
• Wipes Spark with the wallet: deletes its storage and any staged exit data restore, fails the wipe when that fails, clears Spark's in-memory state, and refuses a Spark start while a wipe runs.
• Marks a Transfer to Spending deposit as added on the setting-up screen as soon as Spark lists it as claimed, for Later transfers and Instant ones that land after the 5-minute poll.
• Opens Payment Pending for a Transfer to Spending funding that was signed but not accepted, or that an earlier retained funding blocks, so the original transaction can be inspected and retried at a new fee instead of a generic error.
• Fails the restore of Spark exit data when Spark rejects it while connected, keeping it staged for the next start, so the restore reports it as incomplete.
• Syncs Spark right after it connects, so a first sync the SDK finished before its listener existed is not missed, and starts Spark's event collector only once.
• Rounds a sub-sat amount of a Spark invoice up to the next sat instead of leaving the invoice without an amount.
• Refuses Spark sends while a wallet restore is still pending, before and after the payment is authorized, as master already does for channel sends.
• Returns a Spark Lightning send as soon as it starts, like ldk-node, so its completion event reaches the send screen's watcher instead of firing before it starts.
• Records a Spark send's fee when Spark's next sync reports it, since its completion event carries a fee of 0, and keeps the activity's contact and seen state when re-recording it.
• Shows a Spark withdrawal's arrival in Savings as a transfer from Spending, not a plain received payment, and lists each withdrawal with the fee Spark kept on the Spark screen. The Spark bar reads as empty at a 0 balance.
• Finishes a Transfer to Savings that only withdraws Spark without waiting for a Lightning peer or a fixed pause, so the success screen shows as soon as the withdrawal is sent.

Transfer to Savings selection

• Brings back master's Select funds step (Advanced on the confirm screen) with Spark as one more row beside the channels, in the channel row style, every row on by default, so users can move only their channels or only Spark's balance.
• Moves only what is selected: selected channels close cooperatively as before, Spark withdraws its whole balance to Savings only when its row is on, a Spark-only selection closes no channel, and Continue stays disabled with nothing selected.
• Offers Advanced once there are two items to choose from, counting Spark as one; with Spark alone, or one channel and no Spark balance, confirm moves everything, as master does with one channel.
• Shows on confirm only what is selected: the selected channels' amount plus Spark's balance, and a Spark fee row (Spark's on-chain withdrawal fee) only while Spark is selected. The withdrawal reuses the quote confirm priced, since a second quote from Spark's provider took minutes on regtest.
• Moves Spark's balance only at the fee confirm showed: while Spark is selected, the swipe and Close channel instead wait for the fee and stay off when it can't be priced, with the Spark failure copy, or when the balance less the fee would be dust, with "Amount is too low to transfer to savings."; the withdrawal reads Spark's balance afresh and refuses a fee above the one shown, and a sent withdrawal counts as sent even when the balance read after it fails. It runs once per transfer in the view model, so leaving the progress screen does not cut it short.
• Sizes the swap to savings by what the selected channels can send, not the Spending total that includes Spark, and never swaps when no channel is selected.
• Reports a failed Spark withdrawal instead of the success screen: an error says Spark's balance stayed in Spending, and that the connections are still moving to savings when channels were selected too.
• Marks a Spark withdrawal's arrival in Savings as a transfer from Spending by the txid its send returned, so Home shows no Received Bitcoin sheet for it.

Paykit on Spark

• Publishes the Spark invoice as Bitkit's Paykit Lightning endpoint when no channel can receive, so a Spark-only wallet still lists a Lightning endpoint, and republishes the Paykit endpoints when Spark becomes ready, so a Spark-only wallet offers Lightning to contacts after a cold start. Paykit requests paid over Lightning go through Spark when no channel can carry them.
• Counts Spark's Lightning payments in Paykit's private invoice checks, so an invoice a contact already paid through Spark is replaced instead of published again, and an invoice this wallet already paid through Spark isn't paid twice.
• Settles a Spark send that finished inside the send call, as Spark-to-Spark payments do, by checking Spark's payment list once the send screen starts watching, so a paid Paykit request no longer stays on Payment Pending.
• Reads Spark's payments in Paykit recovery (the Lightning payment status and the proof reconcile), so a request or allowance payment whose Spark completion event was missed settles from Spark's record and its proof reaches the payee. Recovery waits for Spark's first sync before it reads a send as unsent, so an allowance attempt is never recorded as failed while Spark cannot list its payments yet.
• Asks Spark before treating a Lightning payment the node failed as final, in the proof reconcile and the allowance payment status, since a Spark retry of the same invoice shares its hash and decides it.
• Ends a request as failed with its proof removed, and records the allowance attempt as failed, when a Spark send is refused before it leaves (Spark not connected, the payment not preparable, or its fee over the limit); a failure inside the send stays pending. Spark sends keep a request's deadline and an allowance's 1% fee cap, a Spark receive recorded while the app was closed gets its contact, and the Lightning send limit leaves room for Spark's 0.25% service fee.
• Stops loading a payment request the user opened when its payment details fail to resolve, and shows that the contact's payment details aren't ready yet, instead of spinning through 14 retries.

Screen layout

• Keeps the bottom buttons and swipes of the Spark, Transfer to Spending and Transfer to Savings screens at the bottom, with the content scrolling above them on short screens. On short screens the Transfer to Spending number pad shrinks its keys so Continue stays visible.

Out of Scope

• Push notifications for Spark receives: Blocktank's wake notifications go away, and Breez's per-payment webhook is tied to its Lightning address server.
• Spark status: the SDK reports Spark outages; the Spending card doesn't show them yet.
• Raising the wallet-wide claim fee cap so every deposit claims early by itself; the user picks Instant or Later per transfer instead.
• Spark-specific design for the restored transfer screens: they keep the Blocktank-era layout with the copy Spark makes untrue rewritten.
• Funding's Transfer from HW wallet option: it stays disabled; the hardware transfer starts from the hardware wallet screen, as before the sunset.
• Lightning address, LNURL and BOLT12 through Spark.
• bitkit-core: the integration lives in the app, since Breez ships its own Android and iOS bindings and both build beside ldk-node.

Risks for review

• Trust model. Spark is not self-custody in the channel sense: funds are safe while at least one of three operators (Lightspark, Breez, Flashnet) deletes old keys, and 2 of 3 sign. The operator code has a per-wallet freeze switch, and Spark's terms let Lightspark suspend access.
• Exit data backup size. A unilateral exit needs leaf data the SDK keeps on the device, and it can reach several MB. This PR backs it up to VSS as SPARK_EXIT; upstream VSS accepts request bodies up to 1 GiB by default, but a large wallet's upload against Synonym's VSS is untested.
• Fees. Sending Lightning costs 0.25% plus routing; receiving is free for the user (the payer pays 0.15% through route hints). A claim the SDK makes by itself may pay up to the recommended fee plus 2 sat/vB; an Instant claim up to the fastest rate plus 2 sat/vB times 99 vB plus 0.2% of the deposit, which the user accepts on the confirm screen. Withdrawing costs 250 × sat/vB + 750 sats.
• Savings to Spending costs more for small amounts. On mainnet (case 3), a 15,000 sat transfer paid 610 sats on-chain and Spark kept 297 sats to claim it, so Spending got 14,703 sats: 907 sats, about 6% of the transfer. The claim fee is the SDK's standard claim, the fastest recommended fee rate times a 99 vbyte claim transaction (CLAIM_TX_SIZE_VBYTES, deposits.rs), so it is a flat cost that weighs heavily on small transfers. The confirm screen shows it as Spending fee, with To spending after it, for the speed the user picks.
• Slower Savings to Spending without an early claim (UX regression). Blocktank opened a zero-conf channel, so only the order payment needed 1 confirmation, about 10 minutes. Spark claims a deposit after 3 confirmations by default, about 30 minutes. Breez documents faster claims (Claiming on-chain deposits): an instant claim at 0 confirmations, offered for some deposits only, and an expedited claim at 1 or 2 confirmations, both fronted by the Spark Service Provider for a higher fee. On mainnet, case 3's deposit was claimed at 3 confirmations under the earlier automatic cap. The user now picks Instant or Later before the swipe, and an Instant transfer claims early as soon as the provider offers it within the shown ceiling. Whether a deposit gets an early quote, and at which depth, is the provider's call per deposit, so some top-ups still wait for 3 confirmations.
• E2E on regtest. Dev builds connect Spark to Lightspark's hosted regtest with no key, so once this PR leaves draft, E2E specs that expect the Transfer Unavailable sheet take the Spark route whenever that regtest is reachable from CI.
• Closed-app receive. A payment received while the app is closed is claimed on the next sync; it is not signalled by push, so no notification arrives until the app opens.
• No BOLT12 on Spark yet.
• App size. libbreez_sdk_spark_bindings.so adds about 11 MB per ABI (arm64, uncompressed).
• API key and dependency. Mainnet needs a Breez API key, and Lightning goes through a Spark service provider (Lightspark), a dependency like Blocktank was.
• Testing reach. Spark's regtest is Lightspark's hosted chain with no Lightning, so dev builds cannot test Lightning payments or deposits from Bitkit's regtest; on dev, Savings to Spending sends regtest coins to an address Spark never sees unless the build uses ESPLORA_URL.

Design

Restored transfer screens, on the latest Bitkit - Handoff page of the Bitkit Figma file (frame names from docs/screens-map.md; the Spark speed rows, Spending fee and setting-up states have no frame yet):

• Lightning Onboarding From Suggestion Card › Lightning onboarding Intro
• Transfer to Spending Balance From Savings (Channel Opening) › Transfer to Spending Intro, Transfer to Spending Input, Transfer to Spending Confirm, Transfer to Spending Receiving Capacity (now Learn more)
• Funds In Transfer › Transfer to Spending Progress 1
• Transfer to Spending Balance From HW Device › Transfer to Spending Confirm HW, Transfer to Spending Confirmed HW
• Transfer to Savings (Channel Closure) › Transfer to savings select funds, Transfer all funds to savings review (the Spark row and Spark fee have no frame yet)

Figma has no Spark or unlimited-receiving state for the Lightning Connections header, so No limit uses the same style and arrow as the spending figure beside it; @aldertnl, a design for this state is still open.

UI pending design: design was requested in the #design-ux Spark 3.2 thread, and some screens may change after the designers answer. The exit UI polish list isn't part of this PR.

Preview

Transfer to Spending on Spark's regtest chain: the Spend card, both intros, Funding, the amount pad with 25%, Max and delete, confirm with Instant and Later, and Learn more; then an Instant transfer Spark added after 1 confirmation (1adfc47).

Intros, amount and confirm	Instant
t1-intro-amount-confirm2x.mp4	t2-instant-settingup2x.mp4

The setting-up screen for a Later transfer (1adfc47), and for an Instant transfer the provider offered no early claim for (3e60f04).

Later	Instant not available
t3-later-settingup2x.mp4	t4-instant-unavailable2x.mp4

Earlier Spark cases: the Spending invoice from Spark without channels (1, 7aa44f6), and Spark in Lightning Connections with a pending deposit (10, 07a1df7, balance staged with a local hook).

Receive (1)	Lightning Connections → Spark (10)
r1-receive2x.mp4	r72x.mp4

Transfer to Savings selection on Spark's regtest chain (b0169b275, channel rows staged with a local hook): Spark alone goes straight to confirm with its fee; with channels, Advanced lists Spark and each channel, all on, and confirm shows only what is selected.

Spark only	Channels and Spark	Spark and one channel
case1-spark-only-no-channels2x.mp4	case2-channels-and-spark2x.mp4	case3-partial-selection2x.mp4

Channels selected with Spark off (no Spark fee), nothing selected (Continue disabled), and channels with no Spark balance (no Spark row) (b0169b275).

Channels, Spark off	Nothing selected	No Spark balance
case3b-channels-selected-spark-off2x.mp4	case4-nothing-selected2x.mp4	case6-channels-only-no-spark2x.mp4

Spark only picked from the list beside two channels, then swiped (5edd5a8ce): no channel closes, and Savings receives 97,711, the 99,901 balance less the 2,190 Spark fee shown.

case5-spark-only-selected-swipe2x.mp4

Screens

Transfer to Spending

Spending Balance slide	Funding	Transfer to Spending slide	Amount

Confirm, Instant	Confirm, Later	Transfer speed	Setting up, waiting for Spark

Setting up, adding	Setting up, repriced	Setting up, Instant unavailable	Setting up, Later

Setting up, not seen yet	Funds moved	Hardware wallet sign	Hardware wallet signed

Transfer to Savings

Select funds with Spark	Confirm with Spark fee

Lightning Connections

Spark row	Spark detail

QA Notes

Setup

• Mainnet build with BREEZ_API_KEY=<key> in local.properties, and small amounts.
• Dev build (regtest) needs no key (Testing and development). Spark's regtest is Lightspark's own chain, separate from Bitkit's staging regtest, with no Lightning network and no public Electrum server. A dev build runs on it end to end like this:
  1. On the machine running the emulator: python3 scripts/spark-regtest-esplora.py --port 3999. It fronts Spark's regtest mempool API (the SDK's own regtest default, sdk_builder.rs) and adds the two Esplora calls it lacks and ldk-node needs: /fee-estimates at start and /block/<hash>/status for Lightning sync.
  2. Build with ESPLORA_URL=http://10.0.2.2:3999 ./gradlew assembleDevDebug, so the node's chain source is Esplora on Spark's chain instead of Electrum on Blocktank's staging chain. For a phone, run the proxy with --bind 0.0.0.0 and use the host's address.
  3. Fund Savings from Lightspark's web faucet, which needs no credentials, or with FAUCET_USERNAME=… FAUCET_PASSWORD=… python3 scripts/spark-regtest-fund.py <Savings address> 100000 through Lightspark's API faucet (credentials issued by Lightspark; Breez's CI uses the same, faucet.rs).
  4. Savings to Spending, the deposit claim (after 1 confirmation on regtest), Spending to Savings and Spark payments then run on regtest. Two such dev builds pay each other's Lightning invoices as Spark transfers.
  • On 4 Nov, Spark's regtest mempool answered every plain POST /tx with sendrawtransaction RPC error: {"code":-1}, while POST /v1/txs/package accepted the same transaction. If a Savings send fails that way, forward /tx to the package endpoint (a one-element JSON array) in the proxy.
• Transfer to Savings selection (J10 and the recordings above): Spark's regtest has no Lightning peers, so the channel rows were staged with a local hook, not in this PR, that adds two open channels to the Savings screens. The channel cases stop before the swipe; channel closes and the swap are covered by TransferViewModelTest.kt. Channels with no Spark balance was opened through the debug screen link bitkit://screen/savings-availability, since Spending was 0.
• A dev build without ESPLORA_URL stays on Blocktank's staging chain: Spark start-up, invoices and screens work, but its Savings to Spending deposit is never seen by Spark.

Journeys

• J1: updated transfer/spark-transfer-to-spending.xml — with Spark ready, the suggestion card opens the Spending Balance intro and Funding, Transfer from Savings opens the Transfer to Spending intro and the amount screen; 25% and Max fill the amount, confirm shows the four tiles with Instant and Later, Later updates the tiles, Learn more opens and returns; the intros show once.
• J2: updated transfer/transfer-unavailable-sheet.xml — now needs Spark not running, since a ready Spark replaces the sheet.
• J3: restored amount-limits/transfer-spending-over-max.xml — the amount pad caps at Max with the Spending Balance Maximum toast.
• J4: restored amount-limits/transfer-spending-preset-delete.xml — after 25%, Max or a unit switch, each delete removes one digit.
• J5: restored transfer/spending-confirm-amount-change.xml — a lower price at swipe pays at once; a higher one asks for another swipe.
• J6: restored hardware-wallet/transfer-to-spending.xml — a paired Trezor transfers into Spark through amount, sign and signed to the setting-up screen.
• J7: restored hardware-wallet/passphrase-transfer-to-spending.xml — a hidden wallet signs with its live session, re-prompts after the session drops, and refuses a wrong passphrase.
• J8: restored hardware-wallet/transfer-to-spending-node-warmup.xml — a hardware transfer started during node warm-up reaches the sign screen.
• J10: new transfer/savings-select-funds.xml — Select funds lists Spark and each channel, all on; confirm shows only what is selected, with Spark fee only while Spark is selected; Transfer all restores everything; nothing selected disables Continue; stops before the swipe.

Manual Tests

• 18 and 21 cover the entry points; 19 and 20 are retired: they drove the Spark-only deposit screen's Use now and Wait, which the restored setting-up screen replaces (22 to 26).
• 1. Dev, new wallet with no channels → Receive shows Auto and Spending tabs, and the Spending invoice's payee is Spark's node, not the LDK node — Spark's regtest is not in the journey environment.
• 2. Dev, fund Savings, Transfer to Spending → amount max is the on-chain budget, confirm shows the network fee, the Spending fee for the chosen speed and no Advanced, swipe broadcasts to the Spark deposit address — same.
• 3. Mainnet, Transfer to Spending with a small amount → after 3 confirmations the Spending balance shows the amount — mainnet funds.
• 4. Mainnet, no channels, pay a Lightning invoice from another wallet → paid through Spark, activity shows it — mainnet funds.
• 5. Mainnet, no channels, receive a Lightning payment → received sheet and activity show it — mainnet funds.
• 6. Mainnet, receive while the app is closed, then open it → the payment is claimed and shown — mainnet funds.
• 7. Mainnet, Spending to Savings with only a Spark balance → the balance moves on-chain — mainnet funds.
• 8. Mainnet, restore the wallet on another device → the Spark balance comes back — mainnet funds.
• 9. Mainnet, user with an existing channel → payments within channel capacity still go over the channel — mainnet channel.
• 10. Dev or mainnet, Spark with a balance and a deposit in progress → Lightning Connections shows Spark first with its balance and the deposit's confirmations; its detail shows provider, trust note, deposits and Transfer to Savings — Spark state is not in the journey environment.
• 11. Dev, fund Spark from the regtest faucet to the address on the Spark screen → after 1 confirmation Spending shows the amount — faucet is outside the journey environment.
• 12. Dev, two devices with Spark balances, pay one's Spending invoice from the other → paid as a Spark transfer, both show the activity — two devices.
• 13. Dev build with ESPLORA_URL on Spark's regtest chain, Savings funded from the faucet → Transfer to Spending; after 1 confirmation Spark claims the deposit and Spending shows it; Lightning Connections lists it as claimed — Spark's regtest chain.
• 14. Dev, wallet with Spark connected → Backup settings lists Spark exit data as synced; restore the same seed on a fresh install → the log shows Imported Spark exit data before Spark is used, and Spark's balance and deposits match — needs two installs.
• 15. Mainnet, two Bitkit contacts, one Spark-only: the other pays its Paykit request over Lightning, then the Spark-only wallet sends a second Lightning-only request → the second request offers Spending and pays — needs two devices with Paykit.
• 16. Mainnet, Spark send of a Lightning invoice → after Spark's next sync the activity shows the fee Spark charged, not 0 — needs mainnet routing.
• 17. Mainnet, Spark with a balance → Transfer to Savings; the arrival in Savings shows as a transfer, and the Spark screen lists the withdrawal with its fee and an empty bar — needs mainnet.
• 18. Mainnet, Spark ready, no channels → Funding (Spending card) shows Transfer from Savings and Use Other Wallet above Manual Setup; Transfer from Savings opens the Transfer to Spending intro the first time, then the amount screen; Savings → Transfer to Spending opens the same flow — mainnet.
• 21. Build without a Breez API key (Spark off) → Funding and the transfer buttons behave as on master: Manual Setup only and the Transfer Unavailable sheet — any build.
• 22. Mainnet, Transfer to Spending of a small amount with Instant → the setting-up screen says Spark is adding it, then shows Funds moved to spending before 3 confirmations; when the provider asks more than the ceiling, it shows Instant now costs X with Pay and Wait — mainnet funds; the provider decides per deposit.
• 23. Mainnet, same as 22 with Later → the setting-up screen says Spark adds it after 3 confirmations, about 30 minutes, and makes no early claim; the deposit lands after 3 confirmations at about the shown fee — mainnet funds.
• 24. Mainnet, Instant, then on Instant now costs X tap Pay → Spark adds it at X; on Wait → it lands after 3 confirmations — mainnet funds and a repriced quote.
• 25. Mainnet, Instant, leave the setting-up screen at once → the Instant claim still happens within the ceiling — mainnet funds.
• 26. Mainnet, paired Trezor with funds → Hardware wallet → Transfer To Spending, sign on the device → the setting-up screen follows the deposit as in 22 — mainnet funds and a device.
• 37. Dev on Spark's regtest chain with a Spark balance, Transfer to Savings with Spark selected and the withdrawal failing (Wi-Fi and data off before the swipe) → an error says Spark's balance stayed in Spending and no success screen shows; with channels selected too, it says the connections are still moving — needs a failing Spark withdrawal.
• 38. Dev on Spark's regtest chain, Transfer to Savings with Spark selected → when the withdrawal reaches Savings, Home shows no Received Bitcoin sheet and Activity lists it as a transfer — Spark's regtest chain.
• 39. Mainnet, no channels, pay an invoice with Spark and drop the connection right after the swipe → Payment Pending shows, not the error screen; once Spark syncs it settles as sent or failed; paying the same invoice again sends nothing twice — needs a dropped connection mid-send.
• 40. Dev on Spark's regtest chain, Spark balance below its withdrawal fee plus dust → Transfer to Savings with Spark selected shows "Amount is too low to transfer to savings." and the swipe stays off — needs a tiny Spark balance.
• 41. Dev, wallet with Spark exit data backed up → restore the seed on a fresh install with VSS unreachable during the restore: the restore reports Spark exit data as incomplete; once VSS is back, the next upload logs Merged stored Spark exit data before it replaces the stored backup — needs two installs and control of VSS reachability.

Automated Checks

• added SparkRepoTest.kt cases — Instant claims early within the ceiling and reaches Claimed, asks above it, shows the repriced fee from a repriced claim, pays a repriced claim at the new fee, is unavailable with only the standard claim or a declined claim, says Spark has not seen a deposit never listed, and Later makes no claim call; a restored exit backup is imported once Spark connects, one from another network is skipped, a send recorded with fee 0 is re-recorded with the fee a later sync reports, a withdrawal is listed with its fee and its arrival marked as a transfer, and a Spark send refused before it leaves (fee over the limit, past its deadline) is a typed refusal while a failure inside the send is pending
• added SparkFundingViewModelTest.kt — Max is Savings less the network fee and 25% a quarter of it, Max is 0 without Savings, Continue refuses an amount under the Instant fee, prices and opens confirm, the swipe asks again when the fee rose and refuses when Savings no longer cover it, sends at the quoted fee rates and follows the claim at the chosen speed, and a hardware transfer prices from the device and hands signing a transfer request
• added SparkClaimOfferTest.kt — a quote maps to the standard claim, an automatic early claim within the cap, or a choice above the cap or with automatic claiming off, and each claim outcome maps to claimed, waiting, repriced or declined
• added SparkServiceTest.kt — Lightning sends return before completion; the config turns off Breez data sync, the Lightning address server and the default external input parsers on every network; the Later fee prices the mature claim at the half-hour rate (198 sats at 2 sat/vB); connect is refused during a wallet wipe; wipe deletes Spark's storage and a staged exit data restore
• updated ContentViewTest.kt — the spending start route shows the intro until seen, for Savings and hardware wallets, and setting up drops the confirm screen from the back stack
• updated PrivatePaykitRepoTest.kt — a private invoice paid through Spark is replaced on the next refresh
• updated PaykitPaymentProofRepoTest.kt, PaykitAllowancePayerTest.kt, PaykitAllowanceRepoTest.kt, AppViewModelSendFlowTest.kt — a Lightning proof settles from Spark when its event was missed and is removed when Spark failed the send, a send neither rail knows was never made, a Spark send is never read as unsent before Spark has synced, Spark becoming ready or syncing settles open allowance attempts and republishes the Paykit endpoints, Spark sends keep the deadline and fee limit, a receive recorded without its event gets its contact, and the send limit leaves room for Spark's service fee
• updated BackupRepoTest.kt — SPARK_EXIT uploads the exported state and restores it, defers without uploading until Spark has connected and synced, merges the stored backup into Spark before the first upload, never replaces a stored backup it could not read, reports a failed restore as incomplete, and uploads when Spark was ready and synced before observing started
• updated EditInvoiceVMTest.kt — Receive asks for no liquidity or CJIT while Spark can receive
• added DeriveBalanceStateUseCaseTest.kt — Spark balance counts toward Spending, caps max send, and pending deposits count as in transfer
• updated TransferViewModelTest.kt — a selection moves only the picked channels and Spark: Spark only closes no channel and doesn't wait for a peer, channels only leave Spark untouched, both move both; a swap skips Spark when it is deselected and is sized by the selected channels; a quote left from a channel selection never swaps a Spark-only transfer; Spark's fee is priced once per balance and gives up after 15 s; a failed Spark withdrawal is reported while the selected channels still close; Spark is never withdrawn at a fee the user was not shown, and is withdrawn once per confirmed transfer
• updated SparkRepoTest.kt — a Spark withdrawal pays the quote its fee estimate priced while it holds and asks again once it expired or the address changed; its arrival is marked a transfer by the txid its send returned; a withdrawal above the confirmed fee, or leaving dust, never leaves; a failure inside a send ends as failed once Spark has synced and holds no record of it; an invoice in flight, pending or paid is not sent again; the exit backup waits for Spark's first sync; a wipe fails when Spark's storage is not deleted and clears Spark's state; a Max send keeps the routing fee Spark quotes for its whole balance; a Later deposit reads as claimed once Spark claims it; a payment event settles even when the balance read fails; a restore whose exit data Spark rejects fails and keeps it staged; a sent withdrawal succeeds when the refresh after it fails
• updated PaykitPaymentProofRepoTest.kt, PaykitAllowancePayerTest.kt — a Spark retry decides a Lightning payment the node failed
• updated SparkFundingViewModelTest.kt — a funding signed but not accepted opens its recovery instead of an error
• added PaymentFailureReasonExtTest.kt case — Spark and SDK failures show the existing payment failed copy
• updated NotifyPaymentReceivedHandlerTest.kt — an on-chain receive from a Spark withdrawal is a transfer with no received sheet
• updated LightningRepoTest.kt — a Spark send is refused while a wallet restore is pending, or when one begins during authorization
• updated LightningRepoTest.kt, WalletRepoTest.kt, WalletViewModelTest.kt — construct the new Spark dependency, idle, so existing channel paths are unchanged

QA

Each result at the revision it ran on. Dev builds ran on Android 15 and 16 emulators on Spark's hosted regtest; mainnet cases on a Pixel 10 Pro.

• ✅ J1 spark-transfer-to-spending.xml on 4e22b9c, Breez SDK 0.28.0: passed, with Savings funded with 100,000 sats on staging regtest. It passed before on ab1b09d, and by hand on 1adfc47 (recording in Preview).
• ✅ 1. Receive without channels, on 7aa44f6: the Spending invoice's payee was Spark's node with a Spark route hint.
• ✅ 2 and 13. Transfer to Spending on Spark's chain, on 1adfc47: 20,000 sats with Instant were claimed after 1 confirmation (99 sat standard claim, no early offer), and 10,000 sats with Later showed about 99 Spending fee and were claimed at 99 sats.
• ✅ 3. Mainnet Transfer to Spending, on ef7130e: 15,000 sats showed as in transfer within a minute and Spark claimed them after 3 confirmations, keeping 297 sats.
• ✅ 4 and 5. Mainnet with no channel and a 0 Spark balance, on 567e1a8: received 1,024 sats over Lightning and paid 128 from them two minutes later.
• ✅ 7. Mainnet Transfer to Savings of Spark's balance, on a head before the 27 Oct rebase: 12,973 sats withdrew for a 1,470 sat fee and confirmed after 31 minutes.
• ✅ 8. Mainnet wipe and restore on the same phone, on 567e1a8: the Spark balance and claimed deposits came back; not yet run on a second device.
• ✅ 10. Spark in Lightning Connections, on 07a1df7 and a93f3dc (recording in Preview).
• ✅ J10's cases by hand, on b0169b2 and 5edd5a8 with two staged channels: Select funds, partial and empty selections and the Spark fee row as listed; Spark alone swiped reached Funds moved to savings with no channel close, and Savings received 97,711 of 99,901 less the 2,190 fee (recordings in Preview).
• ❌ 14. Restore Spark exit data, on 567e1a8: 0 leaves were imported because the exit data was restored after Spark had synced; fixed in f96bae9, not rerun.
• ❌ 15. Paykit request paid over Spark, on 567e1a8: the payment arrived at once but the payer stayed on Payment Pending; fixed in 024b6bb, not rerun.
• ⏭️ 6, 9, 16 to 18 and 21 to 26: need mainnet funds, a mainnet channel, a Trezor or a build without a Breez key.
• ⏭️ 12: needs two devices.
• ⏭️ 37 and 38: covered by TransferViewModelTest.kt and NotifyPaymentReceivedHandlerTest.kt, not run on a device.
• ⏭️ 39 to 41, and the funding recovery and claim-state fixes in b29e9e5: the pending handling of a Spark send, the Transfer to Savings fee gate and its dust copy, and the SPARK_EXIT merge before the first upload; covered by SparkRepoTest.kt, TransferViewModelTest.kt and BackupRepoTest.kt only. The default external input parsers change is not run on a device either.
• Mainnet chain service: on 5 Nov a read-only mainnet check logged the SDK fetching https://bitkit.to/electrs/fee-estimates, so Spark's fee source works against Bitkit's Esplora.

Models used

• Planning/scoping: claude-opus-5-5 (reasoning: low)
• Implementation: claude-opus-5-5 (reasoning: low)
• Review: claude-sonnet-5-5 (reasoning: Unknown)

The review's session exposes no reasoning-effort setting, so its effort is Unknown.

[ovitrif]

QA:
Tested on a Pixel 10 Pro, mainnet, by @ovitrif, 26–27 Oct; amounts are sats. Balances, names, addresses and txids are masked.

🟢 Restore Spark exit data

Exit data backs up as its own category. After a wipe and restore, the Pixel's Spark balance and claimed deposits came back, but the log counted 0 imported leaves because the exit data was restored after Spark had already synced. Ran on 567e1a8; the order is fixed in f96bae9, and a rerun is pending.

🟢 Claim a deposit

Transfer to Spending: Spark claimed each deposit after 3 confirmations, keeping 297 sats of 15,000 and 198 of 2,500. Ran on an earlier head of this PR, before the 27 Oct rebase.

🟢 Receive with zero balance, then pay

With no channel and a 0 Spark balance, the Pixel received 1,024 sats over Lightning and paid 128 from them two minutes later: Lightning received into Spark is spendable at once. The send's activity showed a fee of 0, fixed in 972e5ec. Ran on 567e1a8.

🟢 Move Spending to Savings

Transfer to Savings withdrew 12,973 sats from Spark for a 1,470 sat fee; the withdrawal showed in Savings unconfirmed after 22 seconds and confirmed after 31 minutes. Ran on an earlier head of this PR, before the 27 Oct rebase; a later run on a build of #1710 lists the withdrawal as a Transfer from Spending.

🟢 Fees against Blocktank

On the same wallet, a 15,000 sat Transfer to Spending cost 907 sats in all through Spark (6.0%) and 1,584 through Blocktank (10.6%). Moving back to Savings cost 1,470 sats through Spark, where Blocktank channel closes cost 183 to 1,113.

🔴 Pay a Paykit request over Spark

The iPhone paid this Pixel's 204 sat Paykit request over Spark and it arrived at once, but the iPhone stayed on Payment Pending; fixed in 024b6bb and synonymdev/bitkit-ios@735e972e, not rerun on a device yet. An earlier attempt failed because this Pixel republished a private invoice already paid through Spark, fixed in 972e5ec.

[ovitrif]

Removed from the 3.1.0 milestone: this draft is the deliverable of a finished Spark experiment and does not ship in 3.1.0.

[ovitrif]

Retargeted this draft to master before merging its base, #1696, so deleting that branch would not close it.

[github-advanced-security]

detekt found more than 20 potential problems in the proposed changes. Check the Files changed tab for more details.

[ovitrif]

Rebuilt this branch on master after the Blocktank sunset (#1696). Master removed the old Transfer to Spending flow, so Spark now has its own amount, confirm and deposit screens, reached from Funding and the transfer buttons while Spark is ready. The deposit screen offers Breez's early claim at the fee the provider quotes for that deposit.

The history was rewritten into new commits, so the shas under Evidence predate the rebuild. This PR stays a draft.

[ovitrif]

Force-pushed: the Spark emergency exit moved to #1782, stacked on this PR, so this branch is now one commit, ab1b09d, on master. The previous head, ab34526, is kept on backup/breez-spark-lightning-20261105.

[ovitrif]

QA after the split, on ab1b09d: 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: every step held. The Spending card opened the intro and Funding (Transfer from Savings and Use Other Wallet above Manual Setup), 25% gave 49,909 of 199,635, Max 199,635, confirm showed 365 network fee, up to 696 Spending fee, 198,939 to spending and 200,000 total; Later showed ≈ 99 and 199,536; Learn more returned with Later kept; Savings › Transfer To Spending then opened the amount screen with no intro.
• ⏭️ J10 savings-select-funds.xml: not run. It needs a Spark balance, funded from Lightspark's regtest faucet, and a staged channel.

J1 to the confirm screen and Learn more, then Savings › Transfer To Spending with no intro (2x speed).

J1 flow	No intro on the second entry
j1-spark-a2x.mp4	j1-spark-b2x.mp4

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-11-06T19:00:52.842752Z	9b76a13	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[ovitrif]

Ready for review. 3.1 is cut, so this opens the Spark work for 3.2. Before marking it ready:

• merged current master;
• ran the full local gate;
• addressed an independent review's findings in 9b76a13.

The QA section lists every case with its revision, and names what's still untested on a device. The emergency exit (#1782) and pay-contacts-via-Spark (#1754) stay stacked on this PR. Some screens may change once the design thread in #design-ux is answered.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9b76a136de

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[greptile-apps]

Confidence Score: 2/5

[Critical impact] The PR changes how Lightning payments and wallet funds move across Bitkit.

Fix the hidden exit-data import errors, missed pending-send results, and missing funding recovery before merging.

Findings

1.  Restore hides failed exit import ▶
2.  Pending send misses its result ▶
3.  Funding hides transaction recovery ▶
4.  Completed deposits keep waiting ▶
5.  Sent withdrawal looks failed ▶

Summary

Adds a Breez-backed Spark wallet alongside LDK and restores transfers between Savings and Spending.

• Spark gives Bitkit another way to receive and pay Lightning invoices.
• Paykit requests can be paid and settled through Spark.
• Savings and hardware-wallet funds can start a Spark transfer with a chosen claim speed.
• Spending-to-Savings transfers can include Spark or selected channels.
• Lightning Connections shows Spark balances and deposits, while VSS stores its exit data.
• Release builds require the Spark key, and regtest builds can use Spark's chain.

No runtime tests or Android visual captures were performed.

Acknowledged scope from ovitrif: Spark receive push notifications, Spark-specific outage status, emergency-exit UI, and further design polish are intentionally outside this PR. The separate hosted regtest chain and its ESPLORA_URL setup are documented limitations, not findings.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  Savings[Savings or hardware wallet] --> Funding[Confirm amount and fees]
  Funding --> Deposit[Send to Spark deposit address]
  Deposit --> Speed{Claim speed}
  Speed -->|Instant| Claim[Request early claim within accepted fee]
  Speed -->|Later| Mature[Wait for confirmations]
  Claim --> Spark[Spark Spending balance]
  Mature --> Spark
  Payment[Lightning payment] --> Capacity{Channels can carry it?}
  Capacity -->|Yes| LDK[LDK channels]
  Capacity -->|No| Spark
  Spark --> Withdrawal[Quoted withdrawal to Savings]
  Spark --> Exit[Export exit data]
  Exit --> Merge[Merge stored backup before first upload]
  Merge --> VSS[Encrypted VSS backup]

Loading

_{Reviews (1) · Last reviewed commit: "fix: harden spark backup, wipe, sends an..." · Reviewed by Greptile}

[ovitrif]

Triage: in 3.2.0. This PR closed no issue, so I filed #1805 to carry the milestone, moved 3.2.0 from this PR to that issue and added Closes at the top of the body. The issue is on the project at 👀 Review. Twin: synonymdev/bitkit-ios#1128 (issue synonymdev/bitkit-ios#1239).

[talosmachina]

No findings. Adds a Breez SDK on Spark wallet: Lightning sends and receives fall back to it when no channel can carry the payment, Savings funds it through the restored Transfer to Spending flow, and its unilateral exit data is backed up to VSS. Reviewed 9b76a13, oversized tier (8,442 added lines in 110 files), static: on the Bitkit track an auto review does not build the branch.

What I checked, and 4 candidates I ruled out

Read in full: SparkService.kt, SparkRepo.kt, the LightningRepo.kt and BackupRepo.kt changes, SparkFundingViewModel.kt, the workflow and Gradle changes.
Not read: the transfer screens, settings screens and the remaining UI files.
CI: lint, build-local and compose-ui green; e2e still pending when reviewed.

Ruled out

• Double send of one invoice: sendsInFlight plus the completed/pending lookup in payInvoice refuse a second send.
• Exit backup overwriting a stored one before merge: uploadSparkExitBackup merges the remote copy first and fails rather than replace one it could not read.
• Spark reconnecting during a wipe: isWiping is set on the service before wipeStorage, and connect refuses while it is set.
• Release without the Breez key: release.yml fails the job when BREEZ_API_KEY is empty; the internal build passes and leaves Spark off, as its comment says.

Merge confidence: 3/5, the oversized tier: the UI remainder was not read.

[ben-kaufman]

This lookup also runs after an LDK send. If an invoice first fails through Spark and is retried once a channel has enough capacity, the old Spark PaymentFailed cancels the LDK watcher here and shows the retry as failed while LDK may still be paying it. Could we settle from the rail used for the current attempt, and cover retries in both directions?

The reverse direction also affects Activity: after a failed LDK attempt succeeds through Spark, onPayment writes the succeeded activity and emits PaymentSuccessful, but handlePaymentSuccessful calls refreshPaymentActivity, which reads the retained LDK failure and overwrites that row as failed in CoreService.processBolt11. That refresh needs the same distinction.