# Bringing up the JVM target What it would actually take to build Mantra for desktop, phased, with the blocking work separated from the mechanical work. The headline is not what you would expect. The four-deep native chain — secp256k1 → bitcoin-kmp → lightning-kmp → lightning-kmp-app — is **already building for JVM**, and has been all along. The thing standing in the way is an empty source set in our own phoenix fork. One scoping note before anything else: **none of this is needed to test the DAOs.** Host-speed Room tests run under `androidUnitTest` today, given one extra dependency. The JVM target is a product decision — a desktop Mantra — not a testing prerequisite. See [Room DAO tests](#appendix-room-dao-tests-do-not-need-this) at the end. ## What is already done for you **The native chain is already JVM.** This is the expensive part, and it is finished. The comment at [composeApp/build.gradle.kts:50](../composeApp/build.gradle.kts) records why: `lightning-kmp-core` publishes no android variant, so our android target resolves it to the **jvm** one, which in turn pulls `secp256k1-kmp-jni-jvm` — desktop `.so`/`.dylib`/`.dll` files. That is why the build has to name `secp256k1-kmp-jni-android` by hand. Read that the other way round and it is good news: every JVM artifact in the chain is already compiled from source, by the composite build, on every android build we do. Turning on a JVM target adds no cinterop, no C compilation, and no new native constraints. **The third-party dependencies all have JVM variants.** Verified against the repositories the build actually resolves from: | dependency | JVM artifact | status | |---|---|---| | quartz 1.14.0 | `com.vitorpamplona.quartz:quartz-jvm` | on Maven Central | | room3 3.0.1 | `androidx.room3:room3-runtime-jvm` | on Google Maven | | sqlite 2.7.0 | `androidx.sqlite:sqlite-bundled-jvm` | on Google Maven | | sqldelight 2.3.2 | `app.cash.sqldelight:jdbc-driver`, `:sqlite-driver` | on Maven Central | **`commonMain` is clean.** No `android.*` and no `java.*` imports anywhere in it. The three NFC files in `androidMain` are not referenced from common code either, so there is nothing to stub out and no android-only API to route around. The shared tree will compile for JVM as-is. ## What actually blocks it `lightning-kmp-app/library` declares 25 `expect` symbols in `commonMain` and implements them across 35 files in `androidMain`. Its `jvmMain` contains exactly one file: ```kotlin // lightning-kmp-app/library/src/jvmMain/kotlin/fibiprops.jvm.kt package io.github.kotlin.fibonacci actual val firstElement: Int = 2 actual val secondElement: Int = 3 ``` That is the Kotlin multiplatform library template's Fibonacci boilerplate, left over from whenever the module was scaffolded. It implements two of the 25 expects, and both of them are the template's own. So **23 JVM actuals are missing**, one level down from us, and `lightning-kmp-app/library/build.gradle.kts:18` has `jvm()` commented out because of it. Mantra cannot declare `jvm()` — commented out in turn at [composeApp/build.gradle.kts:46](../composeApp/build.gradle.kts) — until phoenix does. Everything below is ordered by that dependency. --- ## Phase 0 — build configuration **~half a day. No blockers.** Nothing here needs a decision; it is the groundwork the later phases assume. 1. **Delete the stale `jvmMain` tree.** Six files under `composeApp/src/jvmMain/kotlin/ac/cord/auxiliary/` survive from the old Aux project. They are an orphan source set that nothing currently compiles, which is why they have gone unnoticed — they use the wrong package, import `androidx.room` (Room 2), and reference a long-gone `AuxDatabase`. The moment `jvm()` is declared they become compile errors. Keep them open in a scratch buffer while doing Phase 4: five of them are a usable skeleton for the actuals we still need. 2. **Add the missing catalog entries** to `gradle/libs.versions.toml`: ```toml androidx-sqlite-bundled-jvm = { module = "androidx.sqlite:sqlite-bundled-jvm", version.ref = "sqlite" } sqldelight-sqlite-driver = { module = "app.cash.sqldelight:sqlite-driver", version.ref = "sqldelight" } ``` Only these two, and only because neither can be reached any other way. `sqlite-bundled-jvm` has to be named explicitly because variant-aware resolution hands the *android* artifact to anything running on the host — that is the whole trap described in the appendix. `sqlite-driver` is the jvm counterpart to the `android-driver` and `native-driver` entries already here. No `room3-runtime-jvm` entry: once `jvm()` exists, `commonMain`'s existing `androidx-room3-runtime` resolves to the `-jvm` variant on its own. And the SQLDelight drivers Phase 2 needs belong in **lightning-kmp-app's own catalog**, not this one — that is a separate gradle build with a separate version catalog, and putting them here would not make them visible there. 3. **Do not wire `kspJvm` yet.** It cannot be done at this point, and the reason is already written down a few lines above it in the build file: > These configurations only exist when the ios targets are declared, which > the kotlin block above does only on a mac. The same rule governs `kspJvm` — `dependencies { add("kspJvm", ...) }` throws `UnknownConfigurationException` until a `jvm()` target creates that configuration. So uncommenting [composeApp/build.gradle.kts:194](../composeApp/build.gradle.kts) belongs in **Phase 4**, in the same edit that turns the target on, not here. 4. **Leave `jvm()` commented out**, in both builds. It goes on at the start of Phase 4, once there is something for it to resolve against. Turning it on earlier just means living with a broken build through Phases 1–3. **Verification:** `./gradlew :composeApp:compileDebugKotlinAndroid` still passes. This phase changes nothing observable; the point is that it changes nothing observable — a deleted orphan source set and two unreferenced catalog entries cannot alter a build. **If you are working in a git worktree, no gradle task will run at all** until the submodule is checked out there. Worktrees do not get submodules automatically, so `lightning-kmp-app/` is empty and the composite build fails during configuration: ``` Project with path ':library' not found in build ':lightning-kmp-app' ``` `git submodule update --init --recursive` fixes it, but note that a linked worktree shares `.git/modules/` with the main checkout, so both trees end up sharing one submodule git dir. That is fine while both want the same commit — check with `git submodule status` in each — and worth being careful about when they do not. Then the fresh clones need `local.properties`, which is gitignored and therefore absent, at **five** levels — the mantra root and each of the four nested builds down to secp256k1-kmp. Without it configuration fails at `:lightning-kmp-app:lightning-kmp:bitcoin-kmp:secp256k1-kmp:jni:android` with "SDK location not found": ```bash for d in . lightning-kmp-app \ lightning-kmp-app/experimental/lightning-kmp \ lightning-kmp-app/experimental/lightning-kmp/experimental/bitcoin-kmp \ lightning-kmp-app/experimental/lightning-kmp/experimental/bitcoin-kmp/experimental/secp256k1-kmp; do echo "sdk.dir=$HOME/Android/Sdk" > "$d/local.properties" done ``` --- ## Phase 1 — phoenix: the mechanical actuals **~1–2 days. Blocked by nothing. Do this first.** **Start by turning on `jvm()` in the library** — `lightning-kmp-app/library/build.gradle.kts:18`, not mantra's, which still waits for Phase 4. Without it `library/src/jvmMain/` is an orphan source set that nothing compiles, and every actual in Phases 1–3 would be written blind. With it, `./gradlew :library:compileKotlinJvm` prints the remaining expects by name, and that list is a better worklist than any grep — it shrinks by exactly what you implement and cannot drift from the truth. Fifteen of the 23 are mechanical. None requires a decision — each is either a direct copy of the android implementation or a few lines of JVM file handling. **`DbHooks.jvm.kt` — six functions, and this one is free.** The android implementation is 15 lines and every function is an empty body; the hooks only do work on Apple platforms, where they drive CloudKit sync. Copy the file, change the suffix. ```kotlin actual fun didSaveWalletPayment(id: UUID, database: PaymentsDatabase) {} actual fun didDeleteWalletPayment(id: UUID, database: PaymentsDatabase) {} actual fun didUpdateWalletPaymentMetadata(id: UUID, database: PaymentsDatabase) {} actual fun didSaveContact(contactId: UUID, database: PaymentsDatabase) {} actual fun didDeleteContact(contactId: UUID, database: PaymentsDatabase) {} actual fun makeCloudKitDb(appDb: SqliteAppDb, paymentsDb: SqlitePaymentsDb): CloudKitInterface? = null ``` **`PlatformContext.jvm.kt` — the class plus four directory paths.** On android these come off a `Context`; on desktop there is no context object, so `PlatformContext` becomes either an empty class or one holding an explicit root directory. Prefer the latter — it makes tests and multi-profile desktop installs possible later, and it costs nothing now. The four paths (`getApplicationFilesDirectoryPath`, `getDatabaseFilesDirectoryPath`, `getApplicationCacheDirectoryPath`, `getTemporaryDirectoryPath`) should resolve to a per-OS application data directory, not `java.io.tmpdir`. The old Aux code used tmpdir and left a `TODO` about it; do not inherit that. **The remaining singles:** `platformElectrumRegtestConf` (*not* a copy — android uses `10.0.2.2`, the emulator's alias for the host loopback, and a jvm process is already on the host), `AppVersion`, `phoenixLogWriters` (kermit's `CommonWriter`; android routes into slf4j because android tooling reads that, and the jvm has no equivalent convention), and `computePreferencePath`. **Leave the Fibonacci template alone.** `fibiprops.jvm.kt` looks like stray scaffolding, but it is the jvm half of a pair: `generateFibi` is exercised by template tests in `commonTest`, `androidHostTest`, `iosTest`, `jvmTest` and `linuxX64Test`, and `JvmFibiTest` asserts a value that depends on exactly the two properties that file defines. It already satisfies two of the 25 expects, which is why 23 are missing rather than 25. Deleting the template is a reasonable cleanup of a lightning wallet library, but it is five test files plus four `fibiprops.*` actuals, and it is not this work. **Verification:** `./gradlew :library:compileKotlinJvm` from inside `lightning-kmp-app/`. It still fails at the end of this phase — that is expected, and the failure is the point. It should report **exactly eight** remaining expects, and they should be exactly the contents of Phases 2 and 3: ``` DbFactory.kt createChannelsDbDriver, createPaymentsDbDriver, createAppDbDriver NetworkMonitor.kt NetworkMonitor KeyStoreFunctions.kt keyStoreDecryption, keyStoreEncryption TechnicalExtensions.kt gracefulSingleSeedDecryption, gracefulMultiSeedDecryption ``` Anything else in that list means something in this phase is wrong. Also re-run `./gradlew :composeApp:compileDebugKotlinAndroid` from the mantra root: adding a jvm target to the library must not disturb how the android target resolves it. --- ## Phase 2 — phoenix: drivers and connectivity **~2–3 days. Blocked by nothing, but do it after Phase 1.** Three of the 23 are database drivers and one is the network monitor. These are real implementations, but they are bounded — the shape is known and the failure modes are ordinary. **`DbFactory.jvm.kt` — `createChannelsDbDriver`, `createPaymentsDbDriver`, `createAppDbDriver`.** Use SQLDelight's `sqlite-driver` (the JDBC driver specialised for SQLite). The one real difference from android: the android driver creates and migrates the schema for you via `AndroidSqliteDriver`'s callback, and the JDBC driver does not. You call `Schema.create(driver)` and the migration path explicitly, and you have to track the applied version yourself. Budget for that, not for the driver construction. `createPaymentsDbDriver` also takes an `onError: (String) -> Unit` — make sure corruption and migration failures actually reach it rather than throwing past it, because on android that callback is what surfaces the problem to the user. **`NetworkMonitor.jvm.kt`.** The android implementation is 90 lines built on `ConnectivityManager` and its `NetworkCallback` — genuine push notification of connectivity changes. The JVM has no equivalent. The options are a polling reachability check, or treating the connection as always-available and letting the lightning stack's own reconnect logic handle reality. Start with polling on a slow interval. It is worse than the android behaviour and that is acceptable — the alternative is pretending the network never changes, which produces confusing UI on a laptop that gets closed and reopened. **Verification:** none of this is exercisable until Phase 4. Write the SQLDelight schema-creation path against a scratch `main()` if you want feedback sooner. --- ## Phase 3 — phoenix: key storage **A decision, not a port. Unbounded until the decision is made.** Four of the 23, but only **two** of them are actually a decision. `gracefulSingleSeedDecryption` and `gracefulMultiSeedDecryption` are not. They are pure exception mapping into a `DecryptSeedResult`, and the exception they branch on is `java.security.KeyStoreException` — which exists on the jvm, since `KeyStore` is a plain JCA type. Both are a near-copy of the android actuals and can be written before any of the below is settled. Do them with Phase 2 and leave two errors outstanding rather than four. The decision is `keyStoreEncryption` and `keyStoreDecryption`. The android implementation delegates to `KeystoreHelper.kt` — 116 lines against `AndroidKeyStore`, with `KeyGenParameterSpec`, and `setIsStrongBoxBacked(true)` attempted first and fallen back from when the device has no secure element. The key material never leaves hardware. **Desktop JVM has no equivalent.** There is no portable, hardware-backed keystore on the JVM. The realistic options: | approach | protects against | cost | |---|---|---| | passphrase-derived KEK (Argon2id → AES-GCM) | disk theft, if the passphrase is strong | low; but prompts the user on every launch | | OS keychain via JNA (Keychain / DPAPI / libsecret) | other users on the machine, at rest | three separate platform integrations, three failure modes | | JCEKS/PKCS12 file with a fixed key | nothing meaningful | low, and misleading | This is wallet seed material. The third option is not a stopgap, it is a liability, and it interacts directly with the plaintext-key finding already open against this codebase — do not let a desktop build quietly become the weakest place the seed lives. **Recommendation for sequencing:** implement the passphrase-derived KEK, mark the desktop build clearly as unsuitable for real funds, and treat OS-keychain integration as its own piece of work with its own review. That unblocks Phases 4 and 5 without pretending the security question is answered. **This phase is the only one in the plan with no honest day estimate**, because the estimate is a function of which row of that table gets chosen and how much review it attracts. --- ## Phase 4 — mantra's own actuals **~1–2 days. Blocked by Phases 1–3.** Now turn on `jvm()` — [composeApp/build.gradle.kts:46](../composeApp/build.gradle.kts) and `lightning-kmp-app/library/build.gradle.kts:18` — and, in the same edit, uncomment `kspJvm` at [composeApp/build.gradle.kts:194](../composeApp/build.gradle.kts). Those two go together: the KSP configuration does not exist until the target does, which is why Phase 0 deliberately left it alone. Then let the compiler drive. Mantra declares 16 expects across 8 files. They split cleanly: **Six platform basics.** `getPlatform` ([Platform.kt](../composeApp/src/commonMain/kotlin/press/mantra/compose/Platform.kt)), `PlatformContext`, `AppVersion`, `themeColorScheme` ([Theme.kt](../composeApp/src/commonMain/kotlin/press/mantra/compose/ui/theme/Theme.kt)), and `PlatformDatabaseBuilder`'s two functions. The deleted Aux files from Phase 0 are a working skeleton for five of these — repackage to `press.mantra.compose`, update Room 2 → Room 3 (`androidx.room` → `androidx.room3`), and point at `MantraDatabase` instead of `AuxDatabase`. `MantraDatabaseConstructor` needs no hand-written actual; Room's KSP generates it once `kspJvm` is wired above. For `PlatformDatabaseBuilder.getDatabaseBuilder`, use the real application data directory from Phase 1 — not `java.io.tmpdir`, which is what the old Aux implementation did and which silently loses the database on reboot on most systems. **Nine lightning wrappers.** Four in [Phoenix.kt](../composeApp/src/commonMain/kotlin/press/mantra/compose/extensions/Phoenix.kt) (`platformStartupLogic`, `schedulePlatformLogic`, `getShowIntroFlow`, `getGlobalPrefs`) and five declared in [SovereignWalletViewModel.kt](../composeApp/src/commonMain/kotlin/press/mantra/compose/ui/view/model/SovereignWalletViewModel.kt) (`updateBusinessActiveInUI`, `loadAndDecryptSeed`, `getAvailableWalletsMeta`, and the two `saveAvailableWalletMeta` overloads, plus `platformWriteSeed`) whose android actuals live in `NavigationViewModel.android.kt`. These are thin — they mostly forward into the phoenix library. They are thin *because* Phases 1–3 did the work, which is why they are last. `schedulePlatformLogic` is the one to look at properly: on android it schedules background work through WorkManager. On desktop there is no equivalent and no process that outlives the window. Decide explicitly whether it becomes a no-op or an in-process coroutine, and write down which. **Verification:** `./gradlew :composeApp:compileKotlinJvm`. This is the first point in the plan where the JVM target has to actually resolve, so expect the dependency-substitution surprises to land here rather than earlier. --- ## Phase 5 — desktop entry point and shakeout **~1–2 days. Blocked by Phase 4.** [composeApp/build.gradle.kts:221](../composeApp/build.gradle.kts) already names `press.mantra.desktop.MainKt` as the desktop main class. **That file does not exist.** Write it: a `application { Window { ... } }` entry point constructing `PlatformContext` and handing it to the same root composable android uses. The UI itself is Compose Multiplatform and should largely come up as-is. What to expect anyway: - **Window sizing.** The layouts have only ever been laid out at phone widths. Nothing will crash; plenty will look wrong. - **Back handling.** Android's system back has no desktop counterpart. - **NFC.** The three `androidMain` NFC files are correctly android-only and are not referenced from `commonMain` — but any UI that offers an NFC affordance needs to not offer it here. - **`Dispatchers.IO`.** Used in `getRoomDatabase` and available on JVM, so no change; noted because it is not available on all KMP targets and is easy to trip over later. **Verification:** `./gradlew :composeApp:run`. --- ## Estimate | phase | work | days | blocked by | |---|---|---|---| | 0 | build configuration | 0.5 | — | | 1 | phoenix: mechanical actuals (14) | 1–2 | — | | 2 | phoenix: drivers + network (4) | 2–3 | — | | 3 | phoenix: key storage (4) | **decision** | — | | 4 | mantra actuals (16) | 1–2 | 1, 2, 3 | | 5 | desktop entry point + shakeout | 1–2 | 4 | **Roughly one focused week to a launchable desktop build**, assuming Phase 3 takes the passphrase-derived KEK and the build is marked dev-only. Real desktop key storage is separate work that should not be folded into this estimate, and should land before anyone holds funds on a desktop Mantra. Phases 1, 2 and 3 are independent of each other and can go in parallel if more than one person is on it. Phase 4 cannot start until all three are done, because it is where the compiler finally checks the whole thing. ## Out of scope - **`linuxX64()`** — commented out in the phoenix library at line 53. A native Linux target is a different problem from a JVM one and buys nothing here. - **iOS on a Linux host** — still impossible, for the reasons already documented in both build files. The JVM target does not change that. - **Publishing desktop distributables** — the `compose.desktop` block already declares Dmg/Msi/Deb formats, but signing, notarisation and update channels are untouched by this plan. ## Appendix: Room DAO tests do not need this Worth stating plainly, because the two questions arrived together and the answer to one is not the answer to the other. Room's own [testing guidance](https://developer.android.com/training/data-storage/room/testing-db) recommends host-machine tests over instrumented ones. We can have those today, without a JVM target, because `room3-runtime-android:3.0.1` exposes the no-`Context` builder overload: ``` inMemoryDatabaseBuilder(kotlin.jvm.functions.Function0) ``` and [MantraDatabaseConstructor.kt](../composeApp/src/commonMain/kotlin/press/mantra/compose/database/MantraDatabaseConstructor.kt) already supplies what it needs. So `Room.inMemoryDatabaseBuilder()` compiles in `commonTest` and runs under `testDebugUnitTest`. The one trap is native, and it is the same shape as the secp256k1 problem documented in the build file — in the opposite direction: | artifact | ships | |---|---| | `sqlite-bundled-android` | `jni/{arm64-v8a,armeabi-v7a,x86,x86_64}/libsqliteJni.so` | | `sqlite-bundled-jvm` | `natives/{linux_x64,linux_arm64,osx_*,windows_x64}/` | A local unit test resolves the **android** variant, whose `.so` files the host JVM cannot load, so `BundledSQLiteDriver()` fails at construction. Naming `sqlite-bundled-jvm` on the `androidUnitTest` classpath fixes it. Robolectric does not help and is not needed — it cannot load android `.so` on the host either, and Room's guidance advises against it regardless.