[ovitrif]

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 Spark emergency exit moved to its own PR, #1782, stacked on this one.

Description

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.27.2) 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.
• Turns off Breez's real-time data sync (realTimeSyncServerUrl = null) and its LNURL server (lnurlDomain = null) in Spark's config on every network (3e60f04), so the app sends no traffic to Breez's data-sync or breez.tips LNURL servers and offers no Lightning address.
• 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 again when Spark connects and whenever the SDK reports UnilateralExitStateChanged, and 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. The category shows in Backup settings only where Spark runs.
• 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.
• 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.
• 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.

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.

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 stays uncertain
• 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 and the Lightning address server on every network (3e60f04); the Later fee prices the mature claim at the half-hour rate (198 sats at 2 sat/vB)
• 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, uploads nothing while Spark is not connected, and uploads when Spark was ready 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
• 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
• 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

Tested on Android 15 and Android 16 emulators on Spark's regtest, and on a phone on mainnet for case 3.

🟢 Transfer to Spending intros, amount and confirm, Instant transfer, Later transfer

Transfer to Spending intros, amount and confirm

On 1adfc47 on Spark's regtest chain (J1's steps by hand): the Spend card opened the Spending Balance intro, Funding and the Transfer to Spending intro; 25%, Max and delete worked on the pad, confirm for 50,000 sats showed 458 network fee, up to 397 Spending fee, 49,603 to Spending and 50,458 total, Later and Instant switched the rows, and Learn more opened and returned. Recording in Preview.

---

Instant transfer

On 1adfc47, 20,000 sats with Instant: the setting-up screen waited for Spark to see the deposit, and about a minute after the swipe, after 1 confirmation, Spark claimed it (99 sat standard claim; the provider offered no early claim), Funds moved to spending showed, and the Spark screen listed the deposit as claimed (2, 13). Recording in Preview.

---

Later transfer

On 1adfc47, 10,000 sats with Later: confirm showed about 99 Spending fee and 9,901 to Spending, the setting-up screen said Spark adds it after 3 confirmations, and the Spark screen then listed it as claimed with a 99 sat fee. Recording in Preview.

---

🟢 Earlier Spark cases (1, 3, 10, Spark's chain)

Receive without channels (1)

On 7aa44f6, a new wallet without channels: Receive showed Auto and Spending, and the Spending invoice's payee was Spark's node with a Spark route hint, not the LDK node.

---

Mainnet Transfer to Spending (3)

On ef7130e, on a phone: 15,000 sats to the Spark deposit address showed as in transfer to Spending within a minute, and Spark claimed it with the standard claim after 3 confirmations.

---

Spark in Lightning Connections (10)

On 07a1df7 and a93f3dc: Lightning Connections listed Spark with its balance and a pending deposit at 1/3 confirmations from the app's own broadcast, 26 seconds after the swipe; the detail showed provider, trust note, deposits with their claim fee and Transfer to Savings. Recording in Preview.

---

Node on Spark's chain

On 5f88733, a dev build with ESPLORA_URL started its node on Spark's regtest, synced on-chain and Lightning to the tip with no failed calls at the proxy, and Spark connected beside it.

---

🟢 Transfer to Savings selection

Spark only, no channels

On b0169b2 on Spark's regtest chain, with 99,901 on Spark and no channels: confirm showed 99,901 and a 2,190 Spark fee, with no Advanced button.

---

Channels and Spark, partial and empty selections

On b0169b2 with two staged channels (60,000 and 25,000): confirm showed 184,901 with the Spark fee and Advanced; Select funds listed Spark, Connection 1 and Connection 2, all on. Spark and Connection 1 gave 159,901 with the Spark fee and Transfer all; channels with Spark off gave 85,000 with no Spark fee; nothing selected left Continue disabled.

---

Spark only from the list, swiped

On 5edd5a8 with the two staged channels: Spark alone gave 99,901 and a 2,190 Spark fee; the swipe reached Funds moved to savings at once, no channel close was attempted, and Savings received 97,711.

---

Channels with no Spark balance

On b0169b2 after the withdrawal: Select funds listed only the two channels, confirm showed 85,000 with no Spark fee, and deselecting one left 60,000.

---

🟠 Mainnet cases, Two devices and Paykit, Setting-up repricing, Transfer to Savings failures and arrival

Mainnet cases

Not run: 4 to 9, 16 to 18, 22 to 26 need mainnet funds, a mainnet channel, a Breez key or a Trezor; 21 needs a build without a Breez key.

---

Two devices and Paykit

Not run: 12, 14 and 15 need two installs or two Paykit contacts; the Paykit fixes are covered by the unit tests above.

---

Setting-up repricing

Not run on a device: Spark's regtest provider offered no early claim, so Pay and Wait (24) and Spark hasn't seen your transfer show only in the SettingUpScreen previews and SparkRepoTest.kt.

---

Transfer to Savings failures and arrival

Not run on a device: 37 and 38 landed in d6d853d after the recordings; TransferViewModelTest.kt and NotifyPaymentReceivedHandlerTest.kt cover them. Before that fix, the case 5 withdrawal still showed a Received Bitcoin sheet on Home.

---

Models used

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

[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]

I restored this branch to 171b250, its head before my push at 14:33 CET. That push had put the commits of a stacked branch here by mistake: the Paykit Spark route, 28a63f8 and fea5a92. That work now lives on its own branch, feat/paykit-spark-route, and nothing else on this branch changed.

[github-actions]

Regtest APK

Built from ab1b09d (run).

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

[ovitrif]

A push meant for the Move to Spark branch landed on this PR's branch by mistake, fast-forwarding it to 927472a4e. I force-pushed it back to 5edd5a8ce a minute later; nothing on this branch changed and any CI run for 927472a4e here is stale. The Move to Spark work continues on feat/move-to-spark, stacked on this PR.

[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